Internationalization and Localization¶
To internationalize your extension, the following tasks are required:
Note
Please read carefully the Rules as they are strong constraints for internationalization to work.
Add the token
ITranslator
from@jupyterlab/translation
package to your plugin dependencies.
const extension: JupyterFrontEndPlugin<void> = {
id: 'jupyterlab-extension',
autoStart: true,
requires: [ITranslator],
activate: (app: JupyterFrontEnd, translator: ITranslator) => {}
};
Get the translation bundle from the domain on which your extension is translated.
const trans = translator.load('my_domain');
Note
A good practice is to use your extension named using only letters, numbers and _
characters.
Domain are normalized by replacing -
with _
characters.
Wraps all translatable strings with one of the gettext functions.
Examples:
this._trans.__('String to be translated');
this._trans.__('%1 is argument of a translated string', adjective);
this._trans._n('Singular string for %1', 'Plural string for %1', n);
You could also look at the following pull requests on the spellchecker extension.
Create and publish the translation for your extension.
There are two options: you can either add your extension to the JupyterLab language packs or you can create a python package to distribute your extension translation (see below).
Create translation python package¶
JupyterLab follows Gettext’s approach for translation. Gettext extracts strings from source code, and compiles them with provided translation (find more about it in the Python documentation).
By using jupyterlab-translate, you can extract, update, and compile your translation.
After that, you must include your compiled translation (.json, .mo) to your python package. This can be done by editing these two files.
setup.py:
from setuptools import setup
setup(
# ...
entry_points={"jupyterlab.locale": ["jupyterlab_some_package = jupyterlab_some_package"]},
)
MANIFEST.in:
recursive-include jupyterlab_some_package *.json
recursive-include jupyterlab_some_package *.mo
Note
An example is available in the server test
Settings translation¶
Settings schema can also be translated. The translatable strings are extracted using regex selectors on JSON path. By default, the following selectors are used:
title
: Settings titledescription
: Settings descriptionproperties/.*/title
: Property titlesproperties/.*/description
: Property descriptionsdefinitions/.*/properties/.*/title
: Property titles in definitionsdefinitions/.*/properties/.*/description
: Property descriptions in definitionsjupyter\.lab\.setting-icon-label
: Settings icon label in JupyterLabjupyter\.lab\.menus/.*/label
: Menu label in JupyterLabjupyter\.lab\.toolbars/.*/label
: Toolbar item label in JupyterLab
Those selectors can be configured using the jupyter.lab.internationalization
key in
the schema. The following example will pick the default value for myprop
property:
"jupyter.lab.internationalization": {
"selectors": [
"properties/myprop/default",
],
"domain": "my_jlab_extension"
}
In the example above, a specific domain in which the translations are defined is also
specified (here my_jlab_extension
). If no domain is specified, it defaults to
jupyterlab
.
Rules¶
In order for the strings to be extracted from the code, the following rules must be followed.
Domain name are normalized by replacing
-
to_
Translation bundle variable must be one of:
trans
this.trans
this._trans
this.props.trans
props.trans
Examples that work:
trans.__('This translatable string will be found');
this.trans.__('This translatable string will be found');
this._trans.__('This translatable string will be found');
this.props.trans.__('This translatable string will be found');
props.trans.__('This translatable string will be found');
Examples that will not work:
translator.__('This translatable string WONT be found');
__('This translatable string WONT be found');
this.__('This translatable string WONT be found');
To fix this issue, alter your variable to use an accepted name:
const trans = translator;
trans.__('This translatable string will be found');
String must be passed directly to the function; don’t use variables or constants
Example that will not work:
const errorMessage = 'This translatable string WONT be found'
trans.__(errorMessage);
To fix this issue, pass the string directly:
trans.__('This translatable string will be found');