GitLocker: The Coding Marketplace

Description:

i18next 0.0.3

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.

Term
Description

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:

Parameter
Description
Default value

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

# './locale/en.json':
# {
# "key-1": "Welcome {firstname} {lastname}!",
# "key-2": "Good morning!",
# "key-3": "Bye!"
# }
# './locale/pl.json':
# {
# "key-1": "Witaj {firstname} {lastname}!",
# "key-2": "Dzień dobry!"
# }

config.fallback_lang = 'en'
config.strict = False

en_trans1 = trans('key-1', params={'firstname': 'John', 'lastname': 'Doe'}) # 'Welcome John Doe!'
en_trans2 = trans('key-2') # 'Good morning!'
en_trans3 = trans('key-3') # 'Bye!'

pl_trans1 = trans('key-1', params={'firstname': 'John', 'lastname': 'Doe'}, lang='pl') # 'Witaj John Doe!'
pl_trans2 = trans('key-2', lang='pl') # 'Dzień dobry!'
pl_trans3 = trans('key-3', lang='pl') # 'Bye!' - fallback case because of missing 'key-3' in pl translation

# config.strict=False so key itself is returned when translation key or file is missing
missing_en_trans = trans('missing-key1') # 'missing-key1'
missing_pl_trans = trans('missing-key2', lang='pl') # 'missing-key2'
missing_fr_trans = trans('missing-key3', lang='fr') # 'missing-key3' because translation file is missing

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

# './locale/en.json':
# {
# "key-1": "Welcome {firstname} {lastname}!",
# "key-2": "Good morning!"
# }

config.strict = True

en_trans1 = trans('key-1', params={'firstname': 'John', 'lastname': 'Doe'}) # 'Welcome John Doe!'
en_trans2 = trans('key-2') # 'Good morning!'

# interpolation error
try:
trans('key-1', params={'firstname': 'John'}) # missing lastname
except errors.TranslationFormatError:
...

# missing translation key
try:
trans('missing-key')
except errors.TranslationNotFoundError:
...

# missing translation file
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

CLI to extract translation keys from source code
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:
#1
from i18next import trans
trans("1")

#2
from i18next import trans as _
_("2")

#3
import i18next
i18next.trans("3")

#4
import i18next as _
_.trans("4")

#5
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")