Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
140 lines (98 sloc) 3.94 KB

Internationalising your Plugin

You are free to write your plugin in whatever language you'd like, although if you wish to support multiple languages, NodeBB has a language engine that you can utilise.

Step 1: Directory layout of translations

To begin, let's define some language keys and translations! In your plugin, create a new directory to house your translations. Keep in mind that the structure of the files inside this folder must match that of NodeBB itself: Each sub-directory is named after a language key (e.g. en_GB), and contains .json files housing the translations themselves.

$ cd /path/to/my/plugin
$ mkdir -p languages/en_GB
$ mkdir -p languages/es

In the commands above, I've created my languages folder, with two languages, English (en_GB), and Spanish (es).

Step 2: Add your translations

In the sub-directories created in Step 1, I'll create text files with a .json extension. These file will house the plugin's translations.

In languages/en_GB/myplugin.json:

{
    "greeting": "Hello there! How are you?"
}

In languages/es/myplugin.json:

{
    "greeting": "Hola! Como estás?"
}

Note: Remember to change the name myplugin to something related to your plugin!

Step 3: Tell NodeBB that you have language files to load

NodeBB won't automatically know you have translations to load, so we'll need to add a line to our plugin.json file to tell NodeBB to load our language files.

Open up plugin.json and add a new property called languages:

{
    ...
    "languages": "languages",
    ...
}

The value for this property is the path to wherever your language files reside, relative to the plugin's root folder. In this case, I've placed my languages in a folder called languages directly in my plugin's root folder, so I just need to put in languages. If my languages were in a sub-folder called public, then the correct value here would be public/languages.

Step 4: Use your translations in your plugin

There are a number of ways you can use your translations in your plugin:

Server-side

In your server-side code, you can invoke the translation engine as follows:

var translator = require.main.require('./public/src/modules/translator');

translator.translate('[[myplugin:greeting]]', function(translated) {
    console.log('Translated string:', translated);
});

Client-side

In the browser, you can invoke the translation engine as follows:

require(['translator'], function(translator) {
    translator.translate('[[myplugin:greeting]]', function(translated) {
        console.log('Translated string:', translated);
    });
});

Templates

In your templates, you don't need to do anything special to invoke the translation engine, it is run through automatically, and parses any language strings matching the following syntax: [[resource:key]]. So for our plugin:

<p>[[myplugin:greeting]]</p>

(Optional) Step 5: Tell NodeBB that a particular language is the default

NodeBB itself supports around 40 languages, so you couldn't possibly be expected to translate them into every language! To define a specific language as default, add the defaultLang property to your plugin.json file:

{
    ...
    "languages": "languages",
    "defaultLang": "es",
    ...
}

Now, if a user utilising a language not supported by your plugin loads a language resource for your plugin, they will see the Spanish translation, as it is the designated fallback language.

You can’t perform that action at this time.