i18next 0.0.1+4

A localization formatter based on i18next standard.

i18next

This is an adaptation of i18next standard in dart. This package is still a work in progress. Mind that this is still a pre-1.0.0 so breaking changes may occur frequently.

• ✅ Support for variables
• ✅ Support for namespaces
• ✅ Support for context
• ✅ Support for simple plural forms (one or plural)
• ❌ Support for multiple plural forms (one, few, many, plural, ...)
• ✅ Graceful translation lookup
• ✅ Get string or object tree
• ✅ Support for nesting
• ❌ Sprintf support
• ❌ Retrieve resource files from server
• ❌ Resource caching
• ❌ Custom post processing

Usage

Simply declare the package in your pubspec.yaml

dependencies:
  i18next: ^0.0.1

Then create your instance of I18Next class providing a locale, data source``, and interpolation options`.

I18Next(
  locale,
  (namespace, locale) => /* return your namespace file here */,
    // this can be omitted by the default options
  interpolation: InterpolationOptions(formatter: customFormatter),
);

Syntax

For the simple and straightforward usages:

{
  "key": "Hello World!",
  "nested": {
    "key": "My nested key"
  }
}

i18next.t('key'); // 'Hello World!'
i18next.t('nested.key'); // 'My nested key'

// unmapped keys usually return themselves (when graceful fallback fails)
i18next.t('unspecifiedKey'); // 'unspecifiedKey'

• Basic Interpolation:

{
  "myKey": "Hello {{name}}!"
}

i18next.t('key', arguments: {'name': 'World'}); // 'Hello World!'

• Nesting:

{
  "nesting1": "1 $t(nesting2)",
  "nesting2": "2 $t(nesting3)",
  "nesting3": "3"
}

i18next.t('nesting1'); // "1 2 3"

• Plurals

{
  "key": "item",
  "key_plural": "items",
  "keyWithCount": "{{count}} item",
  "keyWithCount_plural": "{{count}} items"
}

i18next.t('key', count: 0); // 'items'
i18next.t('key', count: 1); // 'item'
i18next.t('key', count: 5); // 'items'
i18next.t('keyWithCount', count: 0); // '0 items'
i18next.t('keyWithCount', count: 1); // '1 item'
i18next.t('keyWithCount', count: 5); // '5 items'

There are also ways of dealing with locales with multiple plural: zero, one, few, many, others (key identifier) (Unsupported)

• Contexts like gender, are marked via underscores

{
    "genderMessage": "They", 
    "genderMessage_male": "Him",
    "genderMessage_female": "Her"
}

i18next.t('genderMessage'); // 'They'
i18next.t('genderMessage', context: 'male'); // 'Him'
i18next.t('genderMessage', context: 'female'); // 'Her'

And can be used with plurals

{
  "friend": "A friend",
  "friend_plural": "{{count}} friends",
  "friend_male": "A boyfriend",
  "friend_female": "A girlfriend",
  "friend_male_plural": "{{count}} boyfriends",
  "friend_female_plural": "{{count}} girlfriends"
}

i18next.t('friend'); // 'A friend'
i18next.t('friend', count: 1); // 'A friend'
i18next.t('friend', count: 100); // '100 friends'

i18next.t('friend', context: 'male', count: 1); // 'A boyfriend'
i18next.t('friend', context: 'female', count: 1); // 'A girlfriend'
i18next.t('friend', context: 'male', count: 100); // '100 boyfriends'
i18next.t('friend', context: 'female', count: 100); // '100 girlfriends'

• Formatting

{
  "key1": "The current date is {{now, MM/DD/YYYY}}",
  "key2": "{{text, uppercase}} just uppercased"
}

i18next.t('key1', arguments: { 'now': DateTime.now() }); // 'The current date is 01/01/2020'
i18next.t('key2', arguments: { 'text': 'my text' }); // 'MY TEXT just uppercased'

There are other usages and possibilities as well, this is just an example of what is defined by this format.

• Namespaces: A namespace can be thought of as logical groupings of different sets of translations. In a given namespace you could have a set of languages, each with their own set of keys. They can also be understood as separate files. For example:

  • common.json: Things that are reused everywhere, eg. Button labels 'save', 'cancel'
  • validation.json: All validation texts
  • glossary.json: Words we want to be reused consistently inside texts

// common.json
{
  "myKey": "This key is in common"
}

// feature.json
{
  "myKey": "This key is in my feature"
}

i18next.t('common:myKey'); // 'This key is in common'
i18next.t('feature:myKey'); // 'This key is in my feature'

There is a way to also set the default namespace or a order of namespaces so a key knows where to start looking for the translation.