i18next - initialization

Documentation:

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

Initialization

i18n.init();

// with options
i18n.init({ lng: "en-US" });
// "later"
var x = i18n.t("key");
 
// with callback
i18n.init(function(err, t) { 
  var x = t("key");
});
 
// with both
i18n.init({ lng: "en-US" }, function(err, t) { 
  var x = t("key");
});

Basic Options

Set language on init:

i18n.init({ lng: 'en-US' }, function(err, t) { /* loading done */ });

Resources will be resolved in this order:

1) try languageCode plus countryCode, eg. 'en-US'
2) alternative look it up in languageCode only, eg. 'en'
3) finally look it up in definded fallback language, default: 'dev'

If language is not set explicitly i18next tries to detect the user language by:

1) querystring parameter (?setLng=en-US)
2) cookie (i18next)
3) language set in navigator

Change language programatically:

Call function i18next.setLng(lng, callback) .

Read out current language set:

Call function i18next.lng() returns current lng.

Set language after init:

i18n.setLng('en-US', function(err, t) { /* loading done */ });

you could fix the language by calling it this way:

i18n.setLng('en-US', { fixLng: true }, function(enUS) { /* done */ });

every call to enUS ( enUS(key, opts) ) will return in enUS even if setLng is called again in different lng

Change the querystring param to lookup lng:

i18n.init({ detectLngQS: 'lang' });

The current locale to set will be looked up in the new parameter: ?lang=en-US

Hint: default would be ?setLng=en-US

Change the cookie name to lookup lng:

i18n.init({ cookieName: 'lang' }); /* default 'i18next' */

The current locale to set and looked up in the given cookie parameter.

Change the cookie domain:

i18n.init({ cookieDomain: '*.mydomain.com' });

Sets the cookie domain to given value.

Disable cookie usage:

i18n.init({ useCookie: false });

Use this only if your sure that language will be provided by the other lookup options or set programatically.

preload additional languages on init:

i18n.init({ preload: ['de-DE', 'fr'] });

The additional languages will be preloaded.

Preload after init:

Call function i18next.preload([lngs], callback).

whitelist languages to be allowed on init:

i18n.init({ lngWhitelist: ['de-DE', 'de', 'fr'] });

Only specified languages will be allowed to load.

load additional namespaces:

i18n.loadNamespace('myNamespace', function() { /* loaded */ });
i18n.loadNamespaces(['myNamespace1', 'myNamespace2'], function() { /* loaded */ });

The additional namespaces will be loaded.

changing the default namespace:

Call function i18next.setDefaultNamespace('myNamespace').

Unset/Set fallback language:

setting one or more fallback language:

i18n.init({ fallbackLng: 'en' });
// or multiple
i18n.init({ fallbackLng: ['fr', 'en'] });

If not set it will default to 'dev'. If turned on, all missing key/values will be sent to this language.

Production Hint: set fallback language to some meaningful language, eg. 'en'

turn fallback language feature off:

i18n.init({ fallbackLng: false });

As the fallbackLng will default to 'dev' you can turn it off by setting the option value to false. This will prevent loading the fallbacks resource file and any futher look up of missing value inside a fallback file.

Unset/Set fallback namespace(s):

with default namespace

// 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.init({ fallbackToDefaultNS: true });
 
i18n.t("namespace2:key1"); // -> value of key 1

with one or more namespace(s)

// given resourcesfile namespace1.en.json
{ 
   key1: 'value of key 1 - ns1' 
}
 
// given resourcesfile namespace2.en.json
{ 
   key1: 'value of key 1 - ns2' 
   key2: 'value of key 2 - ns2' 
}
 
// given resourcesfile namespace3.en.json
{ 
  keys: { 
    2: 'value of key 2',
    3: 'value of key 3'
  }
}
 
i18n.init({ fallbackNS: 'namespace2' });
 
i18n.t("namespace3:key1"); // -> value of key 1 - ns2
 
// array
i18n.init({ fallbackNS: ['namespace1', 'namespace2'] }); // order matters
 
i18n.t("namespace3:key1"); // -> value of key 1 - ns1
i18n.t("namespace3:key2"); // -> value of key 2 - ns2

If a resource can't be found in namespace it will be looked up in default namespace. By

default this option is turned off.

Specify which locales to load:

This will help you optimizing the loading behaviour. In combination with setting fallbackLng to false you can reduce the requests to the server to one!

only load current resource file:

i18n.init({ load: 'current' });

If load option is set to current i18next will load the current set language (this could be a specific (en-US) or unspecific (en) resource file).

Hint: to prevent loading the fallbackLng's resource file set fallbackLng to false.

only load unspecific resource file:

i18n.init({ load: 'unspecific' });

If set to unspecific i18next will always load the unspecific resource file (eg. en instead of en-US).

Hint: to prevent loading the fallbackLng's resource file set fallbackLng to false.

Caching with localStorage:

i18n.init({ 
  useLocalStorage: true | false,
  localStorageExpirationTime: 86400000 // in ms, default 1 week
});

Caching is turned off by default. You might want to turn it on for production.

Warning: if the resouces in a given language had been stored to localStorage they won't be fetched / reloaded from online until set localStorageExpirationTime expired. So if they had been cached once and you add new resources, they won't be reloaded until expired.

But you can easily remove the values from localstorage by calling, eg.: localStorage.removeItem("res_en" )

handling of null values:

// given resourcesfile namespace1.dev.json (fallback lng)
{ 
   key1: 'fallback' 
}
// given resourcesfile namespace1.en.json
{ 
   key1: null 
}
 
i18n.init({ fallbackOnNull: true });
i18n.t('key1'); // -> 'fallback'
 
i18n.init({ fallbackOnNull: false });
i18n.t('key1'); // -> ''

Default is true.

handling of empty string values:

// given resourcesfile namespace1.dev.json (fallback lng)
{ 
   key1: 'fallback' 
}
// given resourcesfile namespace1.en.json
{ 
   key1: '' 
}
 
i18n.init({ fallbackOnEmpty: true });
i18n.t('key1'); // -> 'fallback'
 
i18n.init({ fallbackOnEmpty: false });
i18n.t('key1'); // -> ''

Default is false.

Debug output:

i18n.init({ debug: true });

If something went wrong you might find some helpful information on console log.

Resource Loading

init callback when loaded

i18n.init(callback);

i18n.init(function(err, t) { 
  var appName = t("key");
});

after callback is called you can use the translation function 't' to access your resources in given language.

options to load resources

Pass in resource store:

// tree: lng -> namespace -> key -> nested key
var resources = {
  dev: { translation: { 'key': 'value' } },
  en: { translation: { 'key': 'value' } },            
  'en-US': { translation: { 'key': 'value' } }
};
 
i18n.init({ resStore: resources });

As you provide the resources the callbacks will fire immediatly and no external resources will be loaded!

Adding resources after initialization:

Adding additional resources:

// add a key/value
i18n.addResource('de-CH', 'translation', 'key1', 'value1');
i18n.addResource('de-CH', 'translation', 'deep.key2', 'value2');

// add multipe keys/values
var additionalResources = { 'key1': 'value1', 'deep.key2': 'value2' };
 
i18n.addResourcea('de-CH', 'translation', additionalResources);

Adding additional resource bundles:

var additionalResources = { 'key': 'value1', 'deep': { 'key2': 'value2' } };
 
// addResourceBundle(lng, ns, resources) ns will default to default ns if not provided
i18n.addResourceBundle('de-CH', 'translation', additionalResources);

you can set deep flag to merge with existing values: i18n.addResourceBundle('de-CH', 'translation', additionalResources, true);

Removing additional resource bundles again:

// removeResourceBundle(lng, ns) ns will default to default ns if not provided
i18n.removeResourceBundle('de-CH', 'translation');

Set static route to load resources from:

var option = { resGetPath: 'locales/__lng__/__ns__.json' };
 
i18n.init(option);

Will load 'locales/en-US/translation.json'.

If language is set to 'en-US' following resource files will be loaded one-by-one:

en-US
en
dev (default fallback language)

Hint: to lowercase countryCode in requests, eg. to 'en-us' set option lowerCaseLng = true

Another sample:

var option = { resGetPath: 'locales/__ns__-__lng__.json' };
 
i18n.init(option);

Will load 'locales/translation-en-US.json'.

Overriding ajax loading functionality

You could exchange the ajax loading functionality by providing a custom loader on init:

var option = { 
  customLoad: function(lng, ns, options, loadComplete) {
     // load the file for given language and namespace
 
     // callback with parsed json data
     loadComplete(null, data); // or loadComplete('some error'); if failed
  }
}
 
i18n.init(option);

Load resource dynamically generated on server:

var option = { 
  resGetPath: 'resources.json?lng=__lng__&ns=__ns__',
  dynamicLoad: true 
};
 
i18n.init(option);

Will request 'resources.json?lng=en-US+en+dev&ns=translation'. You will have to assert that the server returns the complete JSON resource Store.

If language is set to 'en-US' following resources will be loaded in one request:

en-US
en
dev (default fallback language)

Change namespace:

var option = { ns: 'resource' };
 
i18n.init(option);

Will load:

'locales/en-US/resource.json'
'locales/en/resource.json'
'locales/dev/resource.json'

Hint: Default namespace is 'translation'.

Multiple namespace:

var option = { 
ns: { 
    namespaces: ['app', 'buttons'], 
    defaultNs: 'app'
  } 
};
 
i18n.init(option, function(err, t) {
  // access default namespace
  var x = t("any.key.from.app")
 
  // to access another namespace prepend [ns]:
  var y = t("buttons:any.key.from.buttons") 
});