alexdefelipe / pi18n

A Python internationalization (i18n) package

Pi18n

Pi18n is an internationalization library for Python

Installation

Install using pip

pip install pi18n

Getting started

Pi18n lets you internationalize your Python app in a simple way. It works like this:

• Provide Pi18n with as many JSON files as languages your app is going to support.
  • Each file will be named with the locale of the language it represents.
  • The content that is going to be placed in the app will be in each of these files, translated into the language that the file represents and associated with a code.
  • The way a translation is associated with a code is by a JSON object: each key of the object is the code, and the value is the translation associated to the code for every language.
  • Every JSON object of every file must have the same keys.
  • Translations can contain named parameters (placeholders) that will be replaced by a certain value on translation-time. Provide as many as needed with this syntax: {param-code}.
• Instantiate an object of TranslationService class. Its constructor must receive:
  1. The path with the translation files.
  2. The default locale.
• Call the get method of the TranslationService instance for getting a translation:
  1. Provide the translation code to the get method as the first argument.
  2. Optionally, provide parameters to the translation either as a dict or as keyword arguments.

Usage

1. Place some translation files in your project

resources/es.json

{
  "HELLO_WORLD": "Hola mundo!",
  "WITH_PARAMS": "Los parámetros son: {fruit1}, {fruit2} and {fruit3}"
}

resources/en.json

{
  "HELLO_WORLD": "Hello world!",
  "WITH_PARAMS": "Params are: {fruit1}, {fruit2} and {fruit3}"
}

2. Create an instance of TranslationService

main.py

from pi18n import TranslationService

translation_service = TranslationService('resources', 'es')

3. Use the TranslationService

Get a translation:

translation = translation_service.get("HELLO_WORLD")
print(f"Message in Spanish: {translation}")

>>> "Message in Spanish: Hola mundo!"

Change locale at runtime:

translation_service.change_locale("en")
translation = translation_service.get("HELLO_WORLD")
print(f"Message in English: {translation}")

>>> "Message in English: Hello world!"

Get a translation that receives some params as a dict:

params = {"fruit1": "apple", "fruit2": "orange", "fruit3": "banana"}
translation = translation_service.get("WITH_PARAMS", params)
print(f"Message with params: {translation}")

>>> "Message with params: Params are: apple, orange and banana"

Get a translation that receives some params as kerword arguments:

translation = translation_service.get("WITH_PARAMS", fruit1="apple", fruit2="orange", fruit3="banana")
print(f"Message with params: {translation}")

>>> "Message with params: Params are: apple, orange and banana"