Rosetta

A general purpose internationalization library in 292 bytes

Internationalization i18n
lukeed/rosettarosetta

README

rosetta


Features


Simple and Familiar API
Unobstrusive and Unopinionated
Less than 300 bytes – including dependencies!

Install


  1. ``` null
  2. $ npm install --save rosetta

  4. ```

Usage


  1. ``` js
  2. import rosetta from 'rosetta';

  4. const i18n = rosetta({
  5.   en: {
  6.     intro: {
  7.       welcome: 'Welcome, {{username}}!',
  8.       text: 'I hope you find this useful.',
  9.     },
  10.     support(obj) {
  11.       let hour = Math.floor(Math.random() * 3) + 9;
  12.       let str = `For questions, I'm available on ${obj.date.toLocaleDateString()}`;
  13.       str += `, any time after ${hour}:00.`
  14.       return str;
  15.     }
  16.   }
  17. });

  19. // set default language
  20. i18n.locale('en');

  22. // add new language
  23. i18n.set('pt', {
  24.   intro: {
  25.     welcome: obj => `Benvind${obj.feminine ? 'a' : 'o'}, ${obj.username}!`,
  26.     text: 'Espero que você ache isso útil.'
  27.   }
  28. });

  30. // append extra key(s) to existing language
  31. i18n.set('pt', {
  32.   support(obj) {
  33.     let hour = Math.floor(Math.random() * 3) + 9;
  34.     let str = `Se tiver perguntas, estou disponível em ${obj.date.toLocaleDateString()}`;
  35.     str += `, qualquer hora depois às ${hour}:00.`
  36.     return str;
  37.   }
  38. });

  40. const data = {
  41.   feminine: false,
  42.   username: 'lukeed',
  43.   date: new Date()
  44. };

  46. // Retrieve translations
  47. // NOTE: Relies on "en" default
  48. i18n.t('intro.welcome', data); //=> 'Welcome, lukeed!'
  49. i18n.t('intro.text', data); //=> 'I hope you find this useful.'
  50. i18n.t('support', data); //=> 'For questions, I'm available on 4/8/2020, any time after 11:00.'

  52. // Retrieve translations w/ lang override
  53. i18n.t('intro.welcome', data, 'pt'); //=> 'Benvindo, lukeed!'

  55. // Change default language key
  56. i18n.locale('pt');

  58. // Retrieve translations w/ new defaults
  59. i18n.t('intro.text', data); //=> 'Espero que você ache isso útil.'
  60. i18n.t('intro.text', data, 'en'); //=> 'I hope you find this useful.'
  61. ```

API


rosetta(dict?)


Returns: Rosetta

Initializes a new Rosettainstance.You may optionally provide an initial translation object.

rosetta.locale(lang?)


Returns: String

Sets the language code for the Rosettainstance.This will cause all rossetta.t() lookups to assume this langcode.

The function will return the currently active langcode. This means that a setting a new value will reply with the same value. Additionally, calling locale()without any argument will return the langcode that the Rosettainstance was last given.

lang


Type: StringRequired: false

The language code to choose.If locale()is called without an argument (or with a falsey value), then the current langcode is returned.

rosetta.set(lang, table)


Merge (or override) translation keys into the langcollection.

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 tablecan correspond to a function or a string template.

When using a function, it will receive the entire data input (see 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 . The key path can use dot-notation to access nested values from the data input (see params ). Additionally, if a key path did not resolve to a value, an empty string is injected.

  1. ``` js
  2. const ctx = rosetta({
  3.   en: {
  4.     foo: (obj) => `function sees "${obj.value || '~DEFAULT~'}"`,
  5.     bar: 'template sees "{{value}}"'
  6.   }
  7. });

  9. ctx.t('foo', {}, 'en');
  10. //=> 'function sees "~DEFAULT~"
  11. ctx.t('foo', { value: 123 }, 'en');
  12. //=> 'function sees "123"

  14. ctx.t('bar', {}, 'en');
  15. //=> 'template sees ""
  16. ctx.t('bar', { value: 123 }, 'en');
  17. //=> 'template sees "123"
  18. ```

Runtime Support


The library makes use of Object shorthand methods and Object.assign .This yields the following support matrix:

| Chrome | Safari | Firefox | Edge | IE | Node.js |
| :--- | :--- | :--- | :--- | :--- | :--- |
| 45+| 9+| 34+| 12+| ❌| 4.0+ |

If you need to support older platforms, simply attach rosettato your project's Babel (or similar) configuration.

Examples


Using Next.js — Thank you @StarpTech Official Next.js example using React Hooks and Context to provide SSR, SSG, CSR compatible i18n solutions.
Localization solution for Next.js — Lightweight Internationalization (i18n) library for Next.js 10+

Credits


Thank you @7sempra for gifting the rosettaname on npm.

License


MIT © Luke Edwards