chalice-babel 1.1.0

Chalice Babel Package

Chalice Babel

Chalice-Babel is a localization package inspired by Flask-Babel for AWS Chalice framework which is uses with help babel, pytz packages. Functionalty is the same like Flask-Babel but this package has a extra feature. You can add your translation strings without touching .po translation files help of export and import feature.

Installation

pip install chalice_babel

Configuration

For the default configuration values you need to add babel_config json into chalicelib/__init__.py file like below example. If not specify Chalice-Babel will use default values below table.

# __init__.py

babel_config = {
    "BABEL_DEFAUL_LOCALE": "en",
    "BABEL_DEFAUL_TIMEZONE": "UTC",
    "BABEL_TRANSLATION_DIRECTORIES": ["translations", "locale"],
    "BABEL_DOMAIN": "messages",
    "LANGUAGES": ["en", "tr"],
}

Chalice-Babel has the following configuration values that can be used to change some internal defaults:

Key	Description
BABEL_DEFAUL_LOCALE	The default locale language when local selector function not used. Default value is "en"
BABEL_DEFAUL_TIMEZONE	The default timezone when local timezone selector functiofunction used. Default value is "UTC"
BABEL_TRANSLATION_DIRECTORIES	List of strings for translations folder names. Default value is "transtalions"
BABEL_DOMAIN	The message domain used by the application. Defaults to "messages".
LANGUAGES	List of language strings you want to support

Usage

To use Chalice-Babel you need to give app you created to Babel object. Jinja support comes default True if you don't want to use jinja support you need to add configre_jinja = False to Babel object.

from chalice import Chalice
from chalice_babel import Babel

app = Chalice(app_name="chalice_babel")
babel = Babel(app)

@babel.localeselector
def get_locale():
    langs = babel.parse_language_header()
    return babel.best_match(langs)

Chalice-Babel uses local selector function returned language code to make translations possible so this decorator needs to be defined. If you need to localize something about time zones additionaly you need to define timezone selector decorator as well.

Format Numbers

To format numbers you can use theese functions:

• format_number()
• format_decimal()
• format_currency()
• format_percent()
• format_scientific()

>>> from chalice_babel import format_number
>>> return format_number(2022)
2,022

>>> from chalice_babel import format_decimal
>>> return format_decimal(2.022)
2,022

>>> from chalice_babel import format_currency
>>> return format_currency(2.022, "USD")
$2,022.00

>>> from chalice_babel import format_percent
>>> return format_percent(20.22)
2,022%

>>> from chalice_babel import format_scientific
>>> return format_scientific(20220000)
2.022E10

Formatting Dates

To format dates you can use below functions. All of them uses datetime objects as first parameter and a format strings as second parameter.

• format_datetime()
• format_date()
• format_time()
• format_timedelta()

>>> from chalice_babel import format_datetime
>>> from datetime import datetime

>>> format_datetime(datetime(1987, 3, 5, 17, 12))
Mar 5, 1987 5:12:00 PM

>>> format_datetime(datetime(1987, 3, 5, 17, 12), 'full')
Thursday, March 5, 1987 5:12:00 PM World (GMT) Time

>>> format_datetime(datetime(1987, 3, 5, 17, 12), 'short')
3/5/87 5:12 PM

>>> format_datetime(datetime(1987, 3, 5, 17, 12), 'dd mm yyy')
05 12 1987

Translating Application

When it comes to translations this is why Chalice-Babel built. It is uses gettext together with Python-Babel. All you need to do import gettext() or ngettext() functions then mark strings or text using one of this functions you want to be translated. To translate singular strings you can use gettext() and if strings have plural form you can use ngettext().

from chalice_babel import gettext, ngettext

gettext(u'A simple string')
gettext(u'Value: %(value)s', value=42)
ngettext(u'%(num)s Apple', u'%(num)s Apples', number_of_apples)

If you want to evaluate strings translation you can use lazy_gettext() function.

After mark all strings you want to translate it is time to create special template file called .pot that contains all the translated strings. Before the creating pot file you need to define babel.cfg configuration file next to your app.py, which is necessary to use pybabel commands.

# babel.cfg
[python: **.py]
[jinja2: **/templates/**.html]
extensions=jinja2.ext.autoescape,jinja2.ext.with_

When you are ready it is time to extract translated strings to .pot file. You all need to do run the following pybabel command.

pybabel extract -F babel.cfg -o messages.pot .

If you used lazy_gettext() function in your application you need to exract this translation strings using this pybabel command.

pybabel extract -F babel.cfg -k lazy_gettext -o messages.pot .

Above commands will generate messages.pot file from babel.cfg configuration file. Now it is time to initialize first translation language.

First of all you should create "en" folder with first command below after that you are free to create other languages you want. This is nessary because export and import command will use this "en" folder as a default. This commands explained in the next section.

 pybabel init -i messages.pot -d chalicelib/translations -l en

 pybabel init -i messages.pot -d chalicelib/translations -l de

-d translation folder which contains language folders. This folder should be located in chalicelib folder. The reason is Chalice packaging this folder when you deploy you application. It you create this folder outside of chalicelib folder translation will not work. If you chooce another name then the translations you should add this name to BABEL_TRANSLATION_DIRECTORIES list in the configuration file.

After you generate your language folders you can edit translations/{language_code}/LC_MESSAGES/messages.pofiles to add your translation strings.

When you done with your translations only you need to compile translations with pybabel compile command.

pybabel compile -d chalicelib/translations

When you changed marked strings or add new translation strings you need to update messages.pot file.

 pybabel update -i messages.pot -d chalicelib/translations

End of this operations some strings can marked fuzzy in .po files. When this happen you need to check and fix manually this strings.

If you need more information for above commands and how Babel works you can checkout babel documentation

Export & Import

When you have a large application with support for many languages, it means that your application contains a lot of strings and text that needs to be translated, and at some point it becomes a pain to manage and replace all those translation files. "export_strings" and "import_strings" commands makes this process easy to manage.

Export

With help of chalice_babel export_strings command you can export all marked translation strings from .po files as a json file and you can easyly check which strings or texts translated correctly or not needs to be translated.

Usage: chalice_babel export_strings [options] [args]

Options:
  -l, --lang               source language for export translation strings, default "en"
  -D, --domain             domains of PO files, default "messages"
  -t, --translation_folder foldername to base directory containing the catalogs under chalicelib folder. Default "translations"
  -o, --output_dir         output path for translation strings json file. Default location is where app.py is located
  -f, --filename           translation strings json filename. Default "translation_strings"

For example if you have "ja" and "de" languages you wanted to support. Export command will generate json file like below.

{
    "currency": {
        "en": "",
        "ja": "",
        "de": ""
    },
    "message": {
        "en": "",
        "ja": "メッセージ",
        "de": "Botschaft"
    },
    "Hello": {
        "en": "",
        "ja": "こんにちわ",
        "de": "Halo"
    }
}

Import

If you generated your translation strings json file now you can edit this file to change or add translations. For example "currency" string didn't translated on above example. You can add translation strings for this key. After that when you run chalice_babel import_strings command this changes will implemented to corresponding .po files. End of this operation you should run pybabel compile.

Usage: chalice_babel import_strings [options] [args]

Options:
  -D, --domain             domains of PO files, default "messages"
  -t, --translation_folder foldername to base directory containing the catalogs under chalicelib folder. Default "translations"
  -o, --input_dir          input path for translation strings json file. Default location is where app.py is located
  -f, --filename           translation strings json filename. Default "translation_strings"

Contributing

Contributions are always welcome!

If you one to help us you can open your pr and we can discuss your new feature.