i18next

Documentation:

There is a nice tutorial in this blog post. Check it out!

Initialization Options
Features
JQuery Integration
Template & Helpers

Translation features

accessing resources

with default namespace
// given resourcefile translation.en.json
{ 
  key1: 'value of key 1' 
}
 
i18n.t("key1"); // -> value of key 1
with namespaces set
// given resourcesfile namespace1.en.json (default ns)
{ 
   key1: 'value of key 1' 
}
 
// given additional resourcesfile namespace2.en.json
{ 
  keys: { 
    2: 'value of key 2',
    3: 'value of key 3'
  }
}
 
i18n.t("key1"); // -> value of key 1
i18n.t("namespace1.key1"); // -> value of key 1
i18n.t("keys.2"); // -> missing key
i18n.t("namespace2:keys.2"); // -> value of key 2
i18n.t("namespace2:keys.3"); // -> value of key 3
using multiple keys (first found will be translated)
// given resourcefile translation.en.json
{ 
  key1: 'value of key 1' 
}
 
i18n.t(["notExists", "key1"]); // -> value of key 1

why this might be useful for you too: see discussion

Hint: You can change namespace and/or key separator by setting options on init:

  • nsseparator = ':::'
  • keyseparator = '::'
  • i18n.t("namespace2:::keys::2"); // -> value of key 2

multiline in json

// given resources in arabic
{           
  'en-US': { 
    translation: {  
      key: [
        "line1",
        "line2",
        "line3"
      ] 
    } 
  }
};

The translation will be joined with '\n'.

Hint: This might be useful in combination with post processing.

arrays in json

// given resources in arabic
{           
  'en-US': { 
    translation: {  
      people: [
        { name: "tom" },
        { name: "steve" }
      ] 
    } 
  }
};
 
i18n.t("key.0.name"); // -> tom

providing a default value

// given resources
{           
  'en-US': { translation: { // key not found } }
};
 
i18n.t("key", { defaultValue: "my text" }); // -> my text
 
// or shorter given i18next.init({ shortcutFunction: 'defaultValue' });
i18n.t("key", "my defalut value");

If a resource key isn't resolvable (en-US -> en -> fallbackLng) than normally the key would be returned as string value. You can provide a better default by passing in option defaultValue.

The default value will be send in sendMissing resources, too.

nested resources

// given resources
{
  dev: { translation: { nesting1: '1 $t(nesting2)' } },
  en: { translation: { nesting2: '2 $t(nesting3)' } },            
  'en-US': { translation: {  nesting3: '3' } }
};
 
i18n.t("nesting1"); // -> 1 2 3

Will return '1 2 3'.

All other options like plurals, ... will work as expected

Hint: You can change pre-/suffix by setting options on init:

  • reusePrefix = '$t(',
  • reuseSuffix = ')',

nested resources with option replace

// given resources
{
  en: { translation: { 
    girlsAndBoys: '$t(girls, {"count": __girls__}) and __count__ boy', 
    girlsAndBoys_plural: '$t(girls, {"count": __girls__}) and __count__ boys' },
    girls: '__count__ girl',
    girls_plural: '__count__ girls' } }
};
 
i18n.t("nesting1", {count: 2, girls: 3}); // -> 3 girls and 2 boys

You could change interpolationPrefix/Suffix (default '__') on need.

replacing variables

// given resources
{           
  'en-US': { translation: {  key: '__myVar__ are important' } }
};
 
i18n.t("key", { myVar: "variables" }); // -> variables are important

Will return 'variables are important'.

You can even have hierarchical variables in form __some.child__.

Hint 1: You can change pre-/suffix by setting options on init or on calling t function with options:

  • interpolationPrefix = '__',
  • interpolationSuffix = '__',

Hint 2: You could even have nested values like:

// given resources
{           
  'en-US': { translation: {  key: '__person.name.first__ is important' } }
};
 
i18n.t("key", { person: { name: { first: 'cristina' } } }); // -> cristina is important

Hint 3: Enscaping:

// given resources
{           
  'en-US': { 
    translation: { 
      key1: Not escaped __nameHTML__,
      key2: Escaped __name__ 
    } 
  }
};
 
i18n.t("key2", { name: '', escapeInterpolation: true }); // -> Escaped <tag>
i18n.t("key1", { name: '', escapeInterpolation: false }); // -> Not escaped <tag>

Adding suffix 'HTML__' to your value will prevent the escaping even if option is set so.

You could turn on escaping on init i18n.init({escapeInterpolation: true}); or by passing in option to t function like in the sample.

Formating:

numbers or currency: You might try numeraljs.

dates or time: You might try momentjs.

sprintf support

// given resources
{           
  'en-US': { translation: {  
    key1: 'The first 4 letters of the english alphabet are: %s, %s, %s and %s',
    key2: 'Hello %(users[0].name)s, %(users[1].name)s and %(users[2].name)s'
  }}
};
 
i18n.t("key1", { postProcess: 'sprintf', sprintf: ['a', 'b', 'c', 'd'] });
i18n.t("key2", { postProcess: 'sprintf', sprintf: { users: [{name: 'Dolly'}, {name: 'Molly'}, {name: 'Polly'}] } } );
|
 // or simpler given i18next.init({ shortcutFunction: 'sprintf' }); 
i18n.t("key1", 'a', 'b', 'c', 'd');

For more information about sprintf and source go to dive.into.javascript.

Hint: You can set i18next to always postProcess with sprintf by init with option postProcess: i18n.init({ postProcess: 'sprintf' });

simple plural

// given resources
{           
  'en-US': { 
    translation: {  
      key: '__count__  child',
      key_plural: '__count__  children' 
    } 
  }
};
 
i18n.t("key", { count: 0 }); // -> 0 children
i18n.t("key", { count: 1 }); // -> 1 child
i18n.t("key", { count: 5 }); // -> 5 children

The variable __count__ is optional.

indefinite plural

// given resources
{           
  'en-US': { 
    translation: {  
      key: '__count__  child',
      key_plural: '__count__  children',
      key_indefinite: 'a child',
      key_plural_indefinite: 'some children' 
    } 
  }
};
 
i18n.t("key", { count: 1, indefinite_article: true }); // -> a child
i18n.t("key", { count: 5, indefinite_article: true }); // -> some children
 
i18n.t("key", { count: 0 }); // -> 0 children
i18n.t("key", { count: 1 }); // -> 1 child
i18n.t("key", { count: 5 }); // -> 5 children

Hint: you can set indefiniteSuffix on init to different value.

multiple plural forms

// given resources in arabic
{           
  'ar': { 
    translation: {  
      key: 'singular',
      key_plural_0: 'zero',
      key_plural_2: 'two',
      key_plural_3: 'few',
      key_plural_11: 'many',
      key_plural_100: 'plural'
    } 
  }
};
 
i18n.t("key", { count:   0 }); // -> zero
i18n.t("key", { count:   1 }); // -> singular
i18n.t("key", { count:   2 }); // -> two
i18n.t("key", { count:   3 }); // -> few
i18n.t("key", { count:   4 }); // -> few
i18n.t("key", { count: 104 }); // -> few
i18n.t("key", { count:  11 }); // -> many
i18n.t("key", { count:  99 }); // -> many
i18n.t("key", { count: 199 }); // -> many
i18n.t("key", { count: 100 }); // -> plural

What did you expect ;).

Hint: i18next provides the functionality for all languages.

You can override the existing rules via 'i18n.pluralExtension.addRule(lng, obj)'

// sample for arabic
i18n.pluralExtension.addRule("ar", {
  "name": "Arabic", 
  "numbers": [ 0, 1, 2, 3, 11, 100 ],
  "plurals": function(n) { return Number(n === 0 ? 0 : n == 1 ? 1 : n == 2 ? 2 : n % 100 >= 3 && n % 100 <= 10 ? 3 : n % 100 >= 11 ? 4 : 5); }
});

Definitions can be found here.

use translation contexts

// given resources
{           
  'en-US': { 
    translation: {  
      friend: 'A friend',
      friend_male: 'A boyfriend',
      friend_female: 'A girlfriend' 
    } 
  }
};
 
i18n.t("friend", { count: 0 }); // -> A friend
i18n.t("friend", { context: 'male' }); // -> A boyfriend
i18n.t("friend", { context: 'female' }); // -> A girlfriend

This feature can be combined with plurals.

eg. key: friend_male_plural: '__count__ boyfriends'

return an objectTree

This might be helpful if you need resources for a plugin or library like moment.js.

// given resources
{           
  'en-US': { 
    translation: {  
      tree: { res: 'added' }
  }
};
 
i18n.t("tree", { returnObjectTrees: true }); // -> { res: 'added' }

Hint: All other features (variables, plurals,...) will be applied befor returning tree.

You can turn on this globally by setting the option in i18n.init({ returnObjectTrees: true }).

manually handle objectTree

This might be helpful if you need resources depending on some app state.

// given resources
{           
  'en-US': { 
    translation: {  
      state: { on: 'online', off: 'offline' }
  }
};
 
 
i18n.init({objectTreeKeyHandler: function(key, value, lng, ns, options)
  return (app.online) ? i18n.t(key + '.on') : i18n.t(key + '.off')
})
 
i18n.t("state", { returnObjectTrees: false }); // -> if app.online online else offline

i18n.init({ objectTreeKeyHandler: function(key, value, lng, ns, options) {...} ).

access value in different language

i18n.t("my.key", { lng: "de-DE" }); // -> will get value in de-DE instead of en-US

You should preload the additional languages on init!

Hint: If the additional language wasn't preloaded it will be fetched synchronous.

access value with different fallback language

i18n.t("my.key", { fallbackLng: "de-DE" }); // -> will get value fallbacking to de-DE

check if a key exists

i18n.exists("my.key", options); // same options as in t function

post processing translations

Adding a post processor

eg. add a post processor parsing markdown.

i18n.addPostProcessor("myProcessorsName", function(value, key, options) {
  return 'some post processed data based on translated value';
});

Using a post processor on translation

i18n.t("my.key", { postProcess: "myProcessorsName" });

i18next will translate the key as usual. Then it passes the translation text to the post processor.

Hint: Alternatively you can set i18next to always postProcess with a specific postProcessor by init with option postProcess: i18n.init({ postProcess: 'myProcessorsName' });

send missing resources to server

Turn it on:

i18n.init({ sendMissing: true });

All keys unable to resolve will be send to: 'locales/add/dev/translation'

Additional Options:

var options = { 
  // change path
  resPostPath: 'locales/add/__lng__/__ns__',
 
  // change sendType
  sendType: 'POST|GET', // default: POST
  
  // send missing values to
  sendMissingTo: 'fallback|current|all',
 
  // change async / sync
  postAsync: true|false // default: true,
 
  // or override the function
  missingKeyHandler: function(lng, ns, key, defaultValue, lngs) { }
}
 
i18n.init(options);

You can send missing values to the fallbackLng, the current language or all languages (eg. 'en-US', 'en', 'fallback') or replace that function completely.

about me

help

legal