A general purpose internationalization library in 298 bytes!

## Features * Simple and Familiar API * Unobstrusive and Unopinionated * Less than 300 bytes – including dependencies! ## Install ``` $ npm install --save rosetta ``` ## Usage ```js import rosetta from 'rosetta'; const i18n = rosetta({ en: { intro: { welcome: 'Welcome, {{username}}!', text: 'I hope you find this useful.', }, support(obj) { let hour = Math.floor(Math.random() * 3) + 9; let str = `For questions, I'm available on ${obj.date.toLocaleDateString()}`; str += `, any time after ${hour}:00.` return str; } } }); // set default language i18n.locale('en'); // add new language i18n.set('pt', { intro: { welcome: obj => `Benvind${obj.feminine ? 'a' : 'o'}, ${obj.username}!`, text: 'Espero que você ache isso útil.' } }); // append extra key(s) to existing language i18n.set('pt', { support(obj) { let hour = Math.floor(Math.random() * 3) + 9; let str = `Se tiver perguntas, estou disponível em ${obj.date.toLocaleDateString()}`; str += `, qualquer hora depois às ${hour}:00.` return str; } }); const data = { feminine: false, username: 'lukeed', date: new Date() }; // Retrieve translations // NOTE: Relies on "en" default i18n.t('intro.welcome', data); //=> 'Welcome, lukeed!' i18n.t('intro.text', data); //=> 'I hope you find this useful.' i18n.t('support', data); //=> 'For questions, I'm available on 4/8/2020, any time after 11:00.' // Retrieve translations w/ lang override i18n.t('intro.welcome', data, 'pt'); //=> 'Benvindo, lukeed!' // Change default language key i18n.locale('pt'); // Retrieve translations w/ new defaults i18n.t('intro.text', data); //=> 'Espero que você ache isso útil.' i18n.t('intro.text', data, 'en'); //=> 'I hope you find this useful.' ``` ## API ### rosetta(dict?) Returns: `Rosetta` Initializes a new `Rosetta` instance.
You may optionally provide an initial translation object. ### rosetta.locale(lang?) Returns: `String` Sets the language code for the `Rosetta` instance.
This will cause all [`rossetta.t()`](#rosettatkey-params-lang) lookups to assume this `lang` code. The function will return the currently active `lang` code. This means that a setting a new value will reply with the same value. Additionally, calling `locale()` without any argument will return the `lang` code that the `Rosetta` instance was last given. #### lang Type: `String`
Required: `false` The language code to choose.
If `locale()` is called without an argument (or with a falsey value), then the current `lang` code is returned. ### rosetta.set(lang, table) Merge (or override) translation keys into the `lang` collection. #### lang Type: `String` The language code to target. #### table Type: `Object` A new record of key-values to merge into the `lang`'s dictionary. Each key within the `table` can correspond to a function or a string template. When using a function, it will receive the entire data input (see [`params`](#params)).
You are required to ensure the function returns a (string) value of your liking. When using a string template, anything within double curly brackets (`{{ example }}`) will be interpreted as a key path and interpolated via [`templite`](https://github.com/lukeed/templite). The key path can use dot-notation to access nested values from the data input (see [`params`](#params)). Additionally, if a key path did not resolve to a value, an empty string is injected. ```js const ctx = rosetta({ en: { foo: (obj) => `function sees "${obj.value || '~DEFAULT~'}"`, bar: 'template sees "{{value}}"' } }); ctx.t('foo', {}, 'en'); //=> 'function sees "~DEFAULT~" ctx.t('foo', { value: 123 }, 'en'); //=> 'function sees "123" ctx.t('bar', {}, 'en'); //=> 'template sees "" ctx.t('bar', { value: 123 }, 'en'); //=> 'template sees "123" ``` ### rosetta.table(lang) Returns: `Object` or `undefined` Retrieve the the `lang`'s full dictionary/table of translation keys. If the language does not exist (aka, no translations have been provided for it), you'll receive `undefined`.
Otherwise, you'll receive the full object as it exists within the `Rosetta` instance. See [`table`](#table). > **Important:** Manipulating this object is any way will mutate and affect your `Rosetta` instance. Be careful! #### lang Type: `String` The language code's table to retrieve. ### rosetta.t(key, params?, lang?) Returns: `String` Retrieve the value for a given `key`. > **Important:** In the normal/default mode, an empty string will be returned for unknown keys.
Conversely, in ["debug" mode](#debugging), an error message will be printed and `undefined` will be returned for unknown keys. #### key Type: `String` or `Array` The identifier to retrieve. A `key` can access nested properties via: * a string that with dot notation — `'foo.bar[1].baz'` * an array of individual key segments — `['foo', 'bar', 1, 'baz']` > **Important:** You are expected to know & traverse your own dictionary structure correctly. ```js const ctx = rosetta({ en: { fruits: { apple: 'apple', } } }); ctx.locale('en'); ctx.t('fruits.apple'); //=> 'apple' ctx.t(['fruits', 'apple']); //=> 'apple' ``` ### params Type: `any`
Optional: `true` The data object argument to pass your dictionary keys' string templates and/or functions. > **Note:** If your *string template* tries to access a key that doesn't exist, an empty string is injected. ```js const ctx = rosetta({ es: { hello: '¡Hola {{name}}!' }, en: { hello(obj) { return obj.name === 'lukeed' ? 'wazzzuppp' : `Hello, ${obj.name}!`; }, }, pt: { hello: 'Oi {{person}}, tudo bem?' // <-- key is wrong }, }); const user1 = { name: 'lukeed' }; const user2 = { name: 'Billy' }; ctx.t('hello', user1, 'es'); //=> '¡Hola lukeed!' ctx.t('hello', user1, 'en'); //=> 'wazzzuppp' ctx.t('hello', user2, 'en'); //=> 'Hello, Billy!' ctx.t('hello', user1, 'pt'); //=> 'Oi , tudo bem?' ``` ### lang Type: `String`
Optional: `true` A language code override without changing the entire `Rosetta` instance's default language. ```js const ctx = rosetta(); ctx.locale('en'); //=> set default ctx.t('greeting', 'lukeed'); //=> (en) 'Hello lukeed!' ctx.t('greeting', 'lukeed', 'es'); //=> (es) '¡Hola lukeed!' ctx.t('bye'); //=> (en) 'Cya' ``` ## Debugging There is a "debug" mode included for **development** environments. The **only** difference with "debug" mode is that [`rossetta.t()`](#rosettatkey-params-lang) will log an error to the console when attempting to access a `key` that does not exist. Conversely, the main/default runtime will quietly return an an empty string for consistent output. Otherwise, the [API](#api) is _exactly_ the same as the main/default export!
This makes it easy to alias or swap the versions for development vs production bundles. Checkout the [Configuration](#configuration) section below for recipes. ```js // debug mode import rosetta from 'rosetta/debug'; const i18n = rosetta({ en: { hello: 'hello' } }); i18n.locale('en'); i18n.t('hello'); //=> 'hello' i18n.t('foobar'); // [rosetta] Missing the "foobar" key within the "en" dictionary //=> undefined ``` > **Note:** With the non-"debug" runtime, an empty string would be returned for the `foobar` key. #### Configuration Here are quick configuration recipes for Rollup and webpack that allow you to choose the right version of `rosetta` for your current environment _without changing you application code_. With both recipes, you will import `rosetta` like this: ```js import rosetta from 'rosetta'; ``` It is up to the bundler to change what `'rosetta'` resolves to... ***Rollup*** You will need to install [`@rollup/plugin-alias`](https://github.com/rollup/plugins/tree/master/packages/alias) before continuing. ```js const isDev = /*custom logic*/ || !!process.env.ROLLUP_WATCH; export default { // ..., plugins: [ // ... require('@rollup/plugin-alias')({ entries: { rosetta: isDev ? 'rosetta/debug' : 'rosetta' } }) ] } ``` ***webpack*** The ability to add aliases within webpack comes by default.
One simply needs to add a [`resolve.alias`](https://webpack.js.org/configuration/resolve/#resolvealias) value depending on the environment: ```js const isDev = /*specific to your config*/; module.exports = { //..., resolve: { alias: { // ..., rosetta: isDev ? 'rosetta/debug' : 'rosetta' } } } ``` ## Runtime Support The library makes use of [Object shorthand methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions#Browser_compatibility) and [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign#Browser_compatibility).
This yields the following support matrix: | Chrome | Safari | Firefox | Edge | IE | Node.js | |:---:|:--:|:---:|:---:|:---:|:----:| | 45+ | 9+ | 34+ | 12+ | :x: | 4.0+ | If you need to support older platforms, simply attach `rosetta` to your project's Babel (or similar) configuration. ## Examples * [**Using Next.js**](https://github.com/zeit/next.js/tree/canary/examples/with-i18n-rosetta) — Thank you [@SharpTech](https://github.com/StarpTech)
_Official Next.js example using React Hooks and Context to provide SSR, SSG, CSR compatible i18n solutions._ ## Credits Thank you [@7sempra](https://github.com/7sempra) for gifting the `rosetta` name on npm. ## License MIT © [Luke Edwards](https://lukeed.com)

	Stars	Issues	Version	Updated	Created
@lingui/core	4,209	35	4.10.0	19 days ago	6 years ago
react-i18next	8,943	11	14.1.1	9 days ago	8 years ago
react-intl	14,072	32	6.6.5	a month ago	10 years ago
rosetta	767	4	1.1.0	4 years ago	11 years ago

@lingui/core vs react-i18next vs react-intl vs rosetta

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past