i18next

i18next is a library facilitating internationalization and localization (i18n) of your Python applications
Rationale
The idea of the project came from the experiences we encountered during the internationalization of projects created
as part of lemon.markets. We were not entirely satisfied with the i18n tools available on the market.
It was mainly about the simplicity of generating translation files, their format, the ease of generating a translation based on a given context or
integration with tools and processes supported by external companies such as localise or phrase.
We figured out we would write our own module that would improve the life of a Python developer in this area.
Please note that this project is in the early development phase.
We would really appreciate if you could help us to improve it. Fell free to report any issue or suggest a new feature.
Installation
You can install library using pip:
pip install i18next
Glossary
The table below describes the terms used in this documentation.
translation key | unique key identifying translation string |
translation string | string to be translated |
translation context | data used to interpolate translation string |
translation file | file containing mapping of translation keys and translation strings |
translation | interpolated translation string |
Locale files
i18next
assumes the existence of the locale directory containing translation files. The locale directory path can be
configured (see section Configuration).
Translation files are JSON files containing mapping between translation keys and translation strings.
The translation file should be named as <language>.json
where<language>
is a language code.
An example of translation file content is presented below:
{
"translation-key-1": "This is a text without interpolation",
"translation-key-2": "This is a text with interpolation: { interpolated-value }"
}
An example directory structure of your locale directory should be similar to:
locale/
en.json
fr.json
es.json
pt.json
...
Configuration
i18next
configuration is being done by modifying global config
object from i18next
package.
It should be done before first usage of trans
function:
from i18next import config
config.fallback_lang = 'en'
config.locale_path = '/path/to/your/locale/directory'
config.strict = False
The table below describes the configuration parameters:
fallback_lang | Fallback language to search for translation key if one cannot be found for requested language | en |
locale_path | Locale directory path | ./locales |
strict | Flag determining the behavior of trans function. If set to False - key itself will be returned in case one has not been found or interpolation has failed , otherwise - exception will be raised | False |
Usage
trans
function is used to get translation based on translation key and requested language.
Non-strict mode
from i18next import trans, config
config.fallback_lang = 'en'
config.strict = False
en_trans1 = trans('key-1', params={'firstname': 'John', 'lastname': 'Doe'})
en_trans2 = trans('key-2')
en_trans3 = trans('key-3')
pl_trans1 = trans('key-1', params={'firstname': 'John', 'lastname': 'Doe'}, lang='pl')
pl_trans2 = trans('key-2', lang='pl')
pl_trans3 = trans('key-3', lang='pl')
missing_en_trans = trans('missing-key1')
missing_pl_trans = trans('missing-key2', lang='pl')
missing_fr_trans = trans('missing-key3', lang='fr')
Strict mode
trans
function is raising exceptions in strict mode (config.strict=True
) when:
- translation file is missing
- translation key does not exist
- interpolation fails
from i18next import trans, config, errors
config.strict = True
en_trans1 = trans('key-1', params={'firstname': 'John', 'lastname': 'Doe'})
en_trans2 = trans('key-2')
try:
trans('key-1', params={'firstname': 'John'})
except errors.TranslationFormatError:
...
try:
trans('missing-key')
except errors.TranslationNotFoundError:
...
try:
trans('key-2', lang='pl')
except errors.TranslationFileNotFoundError:
...
Error handling
Error hierarchy available in strict mode is presented below:
I18nError
- base class for all exceptions thrown within i18next
library
TranslationFileNotFoundError
- missing translation file error
TranslationNotFoundError
- missing translation key error
TranslationFormatError
- interpolation error
i18next
library provides a command line interface to extract translation keys from Python source code.
bash$ i18next --help
usage: i18next [-h] [--locale [LOCALE]] [--lang [LANG]] [--debug] [search_paths ...]
positional arguments:
search_paths Paths to search for python files
options:
-h, --help show this help message and exit
--locale [LOCALE] Locale directory path
--lang [LANG] Language code
--debug, -d Enable debug logging
Basic usage is presented below:
i18next --locale ./locale --lang en --search_paths ./your_package/ ./your/module.py
How it works?
i18next
CLI:
- scans search paths for python files
- extracts translation keys from each file by analysing
trans
function calls
- updates translation file with new translation keys containing empty translations
Translation file to be updated is selected based on language provided in cli call (--lang
).
Please note that currently i18next
is not removing any translation keys from translation file.
Which statements are being detected by the CLI?
As mentioned above, i18next
CLI is detecting translation keys by analysing trans
function calls.
Currently, we support following statements:
from i18next import trans
trans("1")
from i18next import trans as _
_("2")
import i18next
i18next.trans("3")
import i18next as _
_.trans("4")
class A:
def a(self):
from i18next import trans
trans("1")
def b(self):
from i18next import trans as _
_("2")
def c(self):
import i18next
i18next.trans("3")
def d(self):
import i18next as _
_.trans("4")