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.