i18next

https://www.i18next.com
Admin
i18next is a powerful internationalization framework for JavaScript, offering a complete solution...
Tokens:80,056
Snippets:624
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### v1 to v2 migration: nodejs setup

Source: https://www.i18next.com/misc/migration-guide.md

Example of setting up i18next v2 in a Node.js environment with filesystem backend and sprintf postprocessor.

```javascript
var i18next = require('i18next'),
  FilesystemBackend = require('i18next-node-fs-backend'),
  sprintf = require('i18next-sprintf-postprocessor');

i18next
  .use(FilesystemBackend)
  .use(sprintf)
  .init(options, callback);
```

--------------------------------

### Migration code examples

Source: https://www.i18next.com/misc/migration-guide.md

Code examples for migration guide: setting compatibilityJSON to v3 and disabling skipOnVariables.

```javascript
import i18next from 'i18next';

i18next.init({
  compatibilityJSON: 'v3'
}, (err, t) => { /* resources are loaded */ });
```

```javascript
import i18next from 'i18next';

i18next.init({
  interpolation: {
    skipOnVariables: false
  }
}, (err, t) => { /* resources are loaded */ });
```

--------------------------------

### v1 to v2 migration: browser setup

Source: https://www.i18next.com/misc/migration-guide.md

Example of setting up i18next v2 in a browser environment with backend, cache, postprocessor, and language detector modules.

```javascript
import i18next from 'i18next';
import XHR from 'i18next-xhr-backend';
import Cache from 'i18next-localstorage-cache';
import sprintf from 'i18next-sprintf-postprocessor';
import LanguageDetector from 'i18next-browser-languagedetector';

i18next
  .use(XHR)
  .use(Cache)
  .use(sprintf)
  .use(LanguageDetector);
```

--------------------------------

### Migration code examples

Source: https://www.i18next.com/misc/migration-guide.md

Code examples from migration guide sections v7.x.x to v8.0.0 and v6.x.x to v7.0.0.

```javascript
i18next.init({
  fallbackLng: 'en',
  whitelist: ['de', 'en', 'zh'],
  nonExplicitWhitelist: true
});

// eg. `de-AT` will now pass the whitelist check

```

```javascript
fallbackLng: {
  'nb': ['no', 'en'],
  'nn': ['no', 'en'],
  'default': ['en']
}

```

```javascript
import { init, t } from 'i18next';

```

--------------------------------

### v1 to v2 migration: nodejs + express setup

Source: https://www.i18next.com/misc/migration-guide.md

Example of setting up i18next v2 with Express middleware for language detection, missing key handling, and resource serving.

```javascript
var express = require('express');
  i18next = require('i18next'),
  i18nextMiddleware = require('i18next-express-middleware');

i18next
  .use(i18nextMiddleware.LanguageDetector)
  .use(i18nextMiddleware.missingKeyHandler(i18next))
  .use(i18nextMiddleware.getResourcesHandler(i18next));

app.listen(3000);
```

--------------------------------

### createInstance example

Source: https://www.i18next.com/overview/api.md

Example of creating a new i18next instance with options and callback, and the equivalent two-step approach using init.

```javascript
const newInstance = i18next.createInstance({
  fallbackLng: 'en',
  ns: ['file1', 'file2'],
  defaultNS: 'file1',
  debug: true
}, (err, t) => {
  if (err) return console.log('something went wrong loading', err);
  t('key'); // -> same as i18next.t
});

// is the same as
const newInstance = i18next.createInstance();
newInstance.init({
  fallbackLng: 'en',
  ns: ['file1', 'file2'],
  defaultNS: 'file1',
  debug: true
}, (err, t) => {
  if (err) return console.log('something went wrong loading', err);
  t('key'); // -> same as i18next.t
});
```

```typescript
const newInstance = i18next.createInstance({
  fallbackLng: 'en',
  ns: ['file1', 'file2'],
  defaultNS: 'file1',
  debug: true
}, (err, t) => {
  if (err) return console.log('something went wrong loading', err);
  t($ => $.key); // -> same as i18next.t
});

// is the same as
const newInstance = i18next.createInstance();
newInstance.init({
  fallbackLng: 'en',
  ns: ['file1', 'file2'],
  defaultNS: 'file1',
  debug: true
}, (err, t) => {
  if (err) return console.log('something went wrong loading', err);
  t($ => $.key); // -> same as i18next.t
});
```

--------------------------------

### Add Resource Bundle Example

Source: https://www.i18next.com/overview/api.md

Example of adding a resource bundle with deep and overwrite options.

```javascript
i18next.addResourceBundle('en', 'translations', {
  key: 'value',
}, true, true);
```

--------------------------------

### Minimal i18next setup

Source: https://www.i18next.com/how-to/faq.md

Minimal i18next setup without plugins: initialize with inline resources and translate a key.

```javascript
import i18next from 'i18next';

await i18next.init({
  lng: 'en',
  resources: {
    en: { translation: { welcome: 'Welcome' } },
    de: { translation: { welcome: 'Willkommen' } }
  }
});

i18next.t('welcome'); // -> 'Welcome'
```

--------------------------------

### i18next caching examples

Source: https://www.i18next.com/how-to/caching.md

Two JavaScript examples demonstrating i18next caching with filesystem and AsyncStorage backends.

```javascript
import i18next from "i18next";
import ChainedBackend from "i18next-chained-backend";
import HttpBackend from "i18next-http-backend";
import FsBackend from "i18next-fs-backend";

i18next
  .use(ChainedBackend)
  .init({
    fallbackLng: "en",
    // ... your i18next config
    backend: {
      backends: [
        FsBackend,
        HttpBackend
      ],
      backendOptions: [{
        expirationTime: 7 * 24 * 60 * 60 * 1000, // 7 days
        loadPath: './locales_cache/{{lng}}/{{ns}}.json',
        addPath: './locales_cache/{{lng}}/{{ns}}.json' // make sure the folders "locales_cache/{{lng}}" exists
      }, {
        loadPath: '/locales/{{lng}}/{{ns}}.json'
      }]
    }
  });
```

```javascript
import i18next from "i18next";
import ChainedBackend from "i18next-chained-backend";
import HttpBackend from "i18next-http-backend";
import AsyncStorageBackend from "i18next-async-storage-backend";

i18next
  .use(ChainedBackend)
  .init({
    fallbackLng: "en",
    // ... your i18next config
    backend: {
      backends: [
        AsyncStorageBackend,
        HttpBackend
      ],
      backendOptions: [{
        expirationTime: 7 * 24 * 60 * 60 * 1000, // 7 days
        loadPath: 'https://example.com/locales/{{lng}}/{{ns}}.json'
      }]
    }
  });
```

--------------------------------

### cloneInstance example

Source: https://www.i18next.com/overview/api.md

Example of cloning an existing i18next instance with custom options.

```javascript
const newInstance = i18next.cloneInstance({
  fallbackLng: 'en',
  defaultNS: 'file1'
});
```

--------------------------------

### Interpolation examples

Source: https://www.i18next.com/principles/best-practices.md

Examples showing interpolation issues and the recommended self-contained strings approach.

```json
{
    "key": "All fees will be charged to the {{paymentType}} on file for this account."
}
```

```json
{
    "key": "Alle Beträge werden dem {{paymentType}} für dieses Konto in Rechnung gestellt."
}
```

```json
{
    "key1": "All fees will be charged to the credit card on file for this account."
    "key2": "All fees will be charged to the PayPal account on file for this account."

}
```

--------------------------------

### TypeScript formatting samples

Source: https://www.i18next.com/translation-function/formatting.md

TypeScript examples of using the number formatter with options.

```typescript
// JSON
{
  "intlNumber": "Some {{val, number}}",
  "intlNumberWithOptions": "Some {{val, number(minimumFractionDigits: 2)}}"
}

i18next.t($ => $.intlNumber, { val: 1000 });
// --> Some 1,000
i18next.t($ => $.intlNumber, { val: 1000.1, minimumFractionDigits: 3 });
// --> Some 1,000.100
i18next.t($ => $.intlNumber, { val: 1000.1, minimumFractionDigits: 3 });
// --> Some 1,000.100
i18next.t($ => $.intlNumberWithOptions, { val: 2000 });
// --> Some 2,000.000
```

--------------------------------

### JavaScript formatting samples

Source: https://www.i18next.com/translation-function/formatting.md

JavaScript examples of using the number formatter with options.

```javascript
// JSON
{
  "intlNumber": "Some {{val, number}}",
  "intlNumberWithOptions": "Some {{val, number(minimumFractionDigits: 2)}}"
}

i18next.t('intlNumber', { val: 1000 });
// --> Some 1,000
i18next.t('intlNumber', { val: 1000.1, minimumFractionDigits: 3 });
// --> Some 1,000.100
i18next.t('intlNumber', { val: 1000.1, minimumFractionDigits: 3 });
// --> Some 1,000.100
i18next.t('intlNumberWithOptions', { val: 2000 });
// --> Some 2,000.000
```

--------------------------------

### JavaScript Escaping Examples

Source: https://www.i18next.com/translation-function/interpolation.md

JavaScript examples showing the default escaping, the unescaped key prefix, and the escapeValue option.

```javascript
i18next.t('keyEscaped', { myVar: '<img />' });
// -> "no danger &lt;img &#x2F;&gt;"

i18next.t('keyUnescaped', { myVar: '<img />' });
// -> "dangerous <img />"

i18next.t('keyEscaped', { myVar: '<img />', interpolation: { escapeValue: false } });
// -> "no danger <img />" (obviously could be dangerous)
```

--------------------------------

### TypeScript Escaping Examples

Source: https://www.i18next.com/translation-function/interpolation.md

TypeScript examples showing the default escaping, the unescaped key prefix, and the escapeValue option.

```typescript
i18next.t($ => $.keyEscaped, { myVar: '<img />' });
// -> "no danger &lt;img &#x2F;&gt;"

i18next.t($ => $.keyUnescaped, { myVar: '<img />' });
// -> "dangerous <img />"

i18next.t($ => $.keyEscaped, { myVar: '<img />', interpolation: { escapeValue: false } });
// -> "no danger <img />" (obviously could be dangerous)
```

--------------------------------

### Namespace JSON files

Source: https://www.i18next.com/principles/fallback.md

Example JSON files for namespaces: app.json and common.json.

```json
{
  "title": "i18next"
}
```

```json
{
  "button": {
    "save": "save"
  }
}
```

--------------------------------

### i18next JSON v1 resource file example

Source: https://www.i18next.com/misc/json-format.md

Example of i18next JSON v1 resource file showing various features like nesting, interpolation, context, and plurals.

```json
{
  "key": "value",
  "keyDeep": {
    "inner": "value"
  },
  "keyNesting": "reuse $t(keyDeep.inner)",
  "keyInterpolate": "replace this __value__",
  "keyInterpolateUnescaped": "replace this __valueHTML__",
  "keyContext_male": "the male variant",
  "keyContext_female": "the female variant",
  "keyPluralSimple": "the singular",
  "keyPluralSimple_plural": "the plural",
  "keyPluralMultipleEgArabic": "the plural form 0",
  "keyPluralMultipleEgArabic_plural_1": "the plural form 1",
  "keyPluralMultipleEgArabic_plural_2": "the plural form 2",
  "keyPluralMultipleEgArabic_plural_3": "the plural form 3",
  "keyPluralMultipleEgArabic_plural_100": "the plural form 5"
}
```

--------------------------------

### Polyfill for Intl.PluralRules

Source: https://www.i18next.com/how-to/faq.md

Install and import the intl-pluralrules polyfill to support Intl.PluralRules in environments that lack it.

```shell
npm install intl-pluralrules
```

```javascript
import 'intl-pluralrules'
```

--------------------------------

### Adding translations on init

Source: https://www.i18next.com/overview/first-setup-help.md

Example of adding translations directly on init by importing JSON files.

```javascript
import i18next from 'i18next';
import en from './locales/en.json'
import de from './locales/de.json'

i18next
  .init({
    ...opts,
    ...yourOptions,
    resources: {
      en,
      de
    }
  });
```

--------------------------------

### Resource object with two keys

Source: https://www.i18next.com/translation-function/essentials.md

Example resource object with a simple key and a nested key.

```javascript
{
    "key": "value of key",
    "look": {
        "deep": "value of look deep"
    }
}
```

--------------------------------

### Translation File for Fallback Keys

Source: https://www.i18next.com/principles/fallback.md

Example translation file with specific and fallback error messages.

```json
{
  "error": {
    "unspecific": "Something went wrong.",
    "404": "The page was not found."
  }
}
```

--------------------------------

### Loading translations from filesystem with i18next-fs-backend

Source: https://www.i18next.com/overview/first-setup-help.md

Example of using i18next-fs-backend to load translations from the filesystem in a serverless environment.

```javascript
import i18next from 'i18next';
import Backend from 'i18next-fs-backend';

const backend = new Backend({
  // path where resources get loaded from
  loadPath: '/locales/{{lng}}/{{ns}}.json'
});

i18next
  .use(backend)
  .init({
    // initAsync: false, // setting initAsync to false, will load the resources synchronously
    ...opts,
    ...yourOptions
  }); // yourOptions should not include backendOptions!
```

--------------------------------

### Use i18next.format for uppercase formatting

Source: https://www.i18next.com/overview/api.md

Exposes the Formatter's format function. Starting with v26.0.0, this is always backed by the built-in Formatter or a custom Formatter module provided via `.use()`. The JavaScript example uses the string key syntax, while the TypeScript example uses the function key syntax.

```javascript
// key = 'hello {{what}}'
i18next.t('key', { what: i18next.format('world', 'uppercase') }); // -> hello WORLD
```

```typescript
// key = 'hello {{what}}'
i18next.t($ => $.key, { what: i18next.format('world', 'uppercase') }); // -> hello WORLD
```

--------------------------------

### Load plugins with i18next.use

Source: https://www.i18next.com/overview/api.md

Loads additional plugins like backends, language detector, and post-processor. Must be called before init.

```javascript
import i18next from 'i18next';
import Backend from 'i18next-http-backend';
import LocalStorageBackend from 'i18next-localstorage-backend'; // used with i18next-chained-backend for caching
import postProcessor from 'i18next-sprintf-postprocessor';
import LanguageDetector from 'i18next-browser-languagedetector';

i18next
  .use(Backend)
  .use(LocalStorageBackend)
  .use(LanguageDetector)
  .use(postProcessor)
  .init(options, callback);
```

--------------------------------

### v1 to v2 migration: compatibility flags

Source: https://www.i18next.com/misc/migration-guide.md

Example of initializing i18next v2 with compatibility flags to run like v1.11.x.

```javascript
import i18next from 'i18next';

i18next.init({
  compatibilityAPI: 'v1',
  compatibilityJSON: 'v1'
});
```

--------------------------------

### Namespace initialization and key access

Source: https://www.i18next.com/translation-function/essentials.md

Examples of initializing i18next with multiple namespaces, defining translation files, and accessing keys from different namespaces using both string and selector APIs.

```javascript
i18next.init({
  ns: ['common', 'moduleA'],
  defaultNS: 'moduleA'
});
```

```json
{
    "name": "Module A"
}
```

```json
{
    "button": {
        "save": "save"
    }
}
```

```javascript
i18next.t('name');
// -> "Module A"

// from different namespace (not recommended with namespace prefix when used in combination with natural language keys)
i18next.t('common:button.save') // -> "save"
// better use the ns option:
i18next.t('button.save', { ns: 'common' }) // -> "save"
```

```typescript
i18next.t($ => $.name);
// -> "Module A"

// use the ns option:
i18next.t($ => $.button.save, { ns: 'common' }) // -> "save"
```

--------------------------------

### Valid JSON options string example

Source: https://www.i18next.com/translation-function/nesting.md

Shows an example of a translation key with nested options that must be valid JSON for JSON.parse.

```javascript
'sampleKey': 'test $t(nest2, { "changedVarName": "{{var}}" })'
```

--------------------------------

### Initialize i18next with namespaces (TypeScript)

Source: https://www.i18next.com/principles/namespaces.md

TypeScript version of the namespace initialization example. Uses the typed translation function with the $ parameter to access keys. Shows how to specify the namespace via the 'ns' option and load additional namespaces after initialization.

```typescript
i18next.init({
  ns: ['common', 'moduleA', 'moduleB'],
  defaultNS: 'moduleA'
}, (err, t) => {
  i18next.t($ => $.myKey); // key in moduleA namespace (defined default)
  i18next.t($ => $.myKey, { ns: 'common' }); // key in common namespace 

});

// load additional namespaces after initialization
i18next.loadNamespaces('anotherNamespace', (err, t) => { /* ... */ });
```

--------------------------------

### Install i18next with npm or yarn

Source: https://www.i18next.com/overview/getting-started.md

Install i18next using npm or yarn. The default export is UMD compatible (commonjs, requirejs, global).

```bash
# npm
$ npm install i18next --save

# yarn
$ yarn add i18next
```

--------------------------------

### Return objects and arrays with returnObjects (JavaScript)

Source: https://www.i18next.com/translation-function/objects-and-arrays.md

Shows how to use i18next.t with returnObjects: true to return an object or array. The object example passes an interpolation value 'something' and returns the object with the interpolated string. The array example returns the array as-is.

```javascript
i18next.t('tree', { returnObjects: true, something: 'gold' });
// -> { res: 'added gold' }

i18next.t('array', { returnObjects: true });
// -> ['a', 'b', 'c']
```

--------------------------------

### Initialize i18next with namespaces (JavaScript)

Source: https://www.i18next.com/principles/namespaces.md

Initializes i18next with an array of namespaces and sets the default namespace. Shows how to access keys in the default namespace and in a specific namespace using the 'ns' option. Also demonstrates loading additional namespaces after initialization with loadNamespaces.

```javascript
i18next.init({
  ns: ['common', 'moduleA', 'moduleB'],
  defaultNS: 'moduleA'
}, (err, t) => {
  i18next.t('myKey'); // key in moduleA namespace (defined default)
  i18next.t('common:myKey'); // key in common namespace (not recommended with ns prefix when used in combination with natural language keys)
  // better use the ns option:
  i18next.t('myKey', { ns: 'common' });
});

// load additional namespaces after initialization
i18next.loadNamespaces('anotherNamespace', (err, t) => { /* ... */ });
```

--------------------------------

### Initialize i18next with i18next-locize-backend

Source: https://www.i18next.com/how-to/add-or-load-translations.md

Use this snippet to load translations from the locize CDN. Requires a project ID, API key, and reference language. The backend plugin is passed to i18next's use method before initialization.

```javascript
import i18next from 'i18next';
import Backend from 'i18next-locize-backend';

i18next
  .use(Backend)
  .init({
    backend: {
      projectId: '[PROJECT_ID]',
      apiKey: '[API_KEY]',
      referenceLng: '[LNG]'
    }
  });
```

--------------------------------

### TypeScript language override

Source: https://www.i18next.com/translation-function/formatting.md

TypeScript example of overriding the language.

```typescript
i18next.t($ => $.intlNumber, { val: 1000.1, lng: 'de' }); 
// or: i18next.t($ => $.intlNumber, { val: 1000.1, lng: 'de' });
```

--------------------------------

### JavaScript language override

Source: https://www.i18next.com/translation-function/formatting.md

JavaScript example of overriding the language.

```javascript
i18next.t('intlNumber', { val: 1000.1, lng: 'de' }); 
// or: i18next.t('intlNumber', { val: 1000.1, lng: 'de' });
```
Tokens:
Raw