Creating own Plugins

localization as a service Find your translator
Search…
i18next comes with a lot of modules to enhance the features available. There are modules to:
load resources, eg. via xhr or from filesystem (node.js)
cache resources on client, eg. localStorage
detect user language by querystring, navigator, cookie, ...
post processors to further manipulate values, eg. to add sprintf support
The plugins need to support following APIs:
HINT: You can provide a singleton or a prototype constructor (prefered for supporting multiple instances of i18next).
backend
Backend plugins are used to load data for i18next.
1
{
2
  type: 'backend',
3
  init: function(services, backendOptions, i18nextOptions) {
4
    /* use services and options */
5
  },
6
  read: function(language, namespace, callback) {
7
    /* return resources */
8
    callback(null, {
9
      key: 'value'
10
    });
11
​
12
    /* if method fails/returns an error, call this: */
13
    /* callback(truthyValue, null); */
14
  },
15
​
16
  // optional
17
  readMulti: function(languages, namespaces, callback) {
18
    /* return multiple resources - useful eg. for bundling loading in one xhr request */
19
    callback(null, {
20
      en: {
21
        translations: {
22
          key: 'value'
23
        }
24
      },
25
      de: {
26
        translations: {
27
          key: 'value'
28
        }
29
      }
30
    });
31
​
32
    /* if method fails/returns an error, call this: */
33
    /* callback(truthyValue, null); */
34
  },
35
​
36
  // only used in backends acting as cache layer
37
  save: function(language, namespace, data) {
38
    // store the translations
39
  },
40
​
41
  create: function(languages, namespace, key, fallbackValue) { 
42
    /* save the missing translation */
43
  }
44
}
Copied!
Using readMulti is only supported when using the https://github.com/i18next/i18next-multiload-backend-adapter​
languageDetector
Language Detector plugins are used to detect language in user land.
1
{
2
  type: 'languageDetector',
3
  async: true, // If this is set to true, your detect function receives a callback function that you should call with your language, useful to retrieve your language stored in AsyncStorage for example
4
  init: function(services, detectorOptions, i18nextOptions) {
5
    /* use services and options */
6
  },
7
  detect: function(callback) { // You'll receive a callback if you passed async true
8
    /* return detected language */
9
    // callback('de'); if you used the async flag
10
    return 'de';
11
  },
12
  cacheUserLanguage: function(lng) {
13
    /* cache language */
14
  }
15
}
Copied!
post processor
Post Processors are used to extend or manipulate the translated values before returning them in t function.
(Post Processors do not need to be prototype functions)
1
{
2
  type: 'postProcessor',
3
  name: 'nameOfProcessor',
4
  process: function(value, key, options, translator) {
5
    /* return manipulated value */
6
    return value;
7
  }
8
}
Copied!
logger
Override the built in console logger.
(loggers do not need to be prototype functions)
1
{
2
  type: 'logger',
3
​
4
  log: function(args) {},
5
  warn: function(args) {},
6
  error: function(args) {}
7
}
Copied!
Helpful tips
Make sure to set the plugin type
If you do not set the plugin type, you may get an error like this.
... No [plugin type] was added via i18next.use. Will not load resources.
If you are creating a class for your plugin, you may set the type like in the following example (the following is an example if you are making a backend plugin):
1
class Backend {
2
  constructor(services, backendOptions, i18nextOptions){
3
​
4
  }
5
​
6
  // other required methods;
7
  // ie. read, create, etc.
8
}
9
Backend.type = "backend";
10
​
11
export default Backend;
Copied!
Create a private method to initialize your plugin
The constructor of your plugin (if the plugin is of type backend or languageDetector) will be called without arguments if you use the plugin as a class. Using the plugin as a class looks like this:
1
import i18n from "i18next";
2
import {
3
  initReactI18next
4
} from "react-i18next";
5
import i18nBackend from "my-custom-backend";
6
​
7
i18n
8
  .use(i18nBackend)
9
  .use(initReactI18next)
10
  .init({
11
    backend: {
12
      // custom options
13
    },
14
    // other options
15
  });
Copied!
While using your plugin in this way, you may want to validate the options passed into the backend property of the .init method. A good way to validate them is to have a private method where you initialize your plugin.
1
class Backend {
2
  constructor(services, backendOptions = {}, i18nextOptions = {}){
3
    this.init(services, backendOptions, i18nextOptions);
4
  }
5
​
6
  init(services, backendOptions, i18nextOptions){
7
    // Validate backendOptions
8
  }
9
​
10
  // other required methods;
11
  // ie. read, create, etc.
12
}
13
Backend.type = "backend";
14
​
15
export default Backend;
Copied!
Last modified 7mo ago
Copy link
Contents
Make sure to set the plugin type
Create a private method to initialize your plugin