Language Packs

Fietsboek allows language files to be distributed as third-party-packages, such that you can localize Fietsboek without needing to add the files to the main repository. This way, language packs can be updated independently of Fietsboek, and packs can be provided for languages that are not “officially supported”.

The basic concept behind language packs is the same as in normal localization, except that the files are in a different Python package. If you are familiar with the gettext machinery, you can simply create a Python package that has a locale/ folder in the same structure as Fietsboek’s.

In the following guide, we will create an example language pack for Dutch ("nl").

Preqrequisites

In order to create a translation package, you need access to the source code of Fietsboek and Babel. The easiest way to get both is to clone the git repository, and use a virtual environment to install babel:

git clone https://gitlab.com/dunj3/fietsboek.git
FB_PATH=$PWD/fietsboek/fietsboek
virtualenv /tmp/babel
/tmp/babel/pip install Babel
BABEL=/tmp/babel/bin/pybabel

Creating a Package

Language packs are normal Python packages, as such, you can use any tool you’d like to create a pack — as long as you make sure to include the package data. In our example, we will use Poetry, as that is what Fietsboek itself uses.

To create a basic package, we will pick a path in which to create our pack: ~/fb-i18n-nl and create the basic structure:

PACK_PATH=~/fb-i18n-nl
mkdir -p $PACK_PATH/fb_i18n_nl
touch $PACK_PATH/fb_i18n_nl/__init__.py
mkdir $PACK_PATH/fb_i18n_nl/locale

And the content of $PACK_PATH/pyproject.toml:

[tool.poetry]
name = "fb-i18n-nl"
version = "0.1.0"
description = ""
authors = ["Jan Modaal <jan.modaal@example.com>"]
packages = [{include = "fb_i18n_nl"}]

[tool.poetry.dependencies]
python = "^3.7"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Note

You can also use poetry new to create the basic package, just make sure to remove the unnecessary files.

Initializing the Language

This is the same process as for built-in languages, except that you need to adjust the paths:

$BABEL init -d $PACK_PATH/fb_i18n_nl/locale -l nl -i $FB_PATH/locale/fietslog.pot

You can also copy over the English HTML files, which makes it easier to translate them:

cp -rv $FB_PATH/locale/en/html $PACK_PATH/fb_i18n_nl/locale/nl

Don’t forget to adjust the locale/.../DISPLAY_NAME file to give your language pack the correct human-readable representation.

Translating & Compiling

Update the messages.po file in $PACK_PATH/fb_i18n_nl/locale/nl/LC_MESSAGES/messages.po, as well as the HTML files in $PACK_PATH/fb_18n_nl/locale/nl/html.

Once the messages have been translated, you can compile the resulting file:

$BABEL compile -d $PACK_PATH/fb_i18n_nl/locale -l nl -i $PACK_PATH/fb_i18n_nl/locale/nl/LC_MESSAGES/messages.po

Installing the Language Pack

You can install the language pack like a normal Python package:

pip install $PACK_PATH

And enable it in your settings:

fietsboek.language_packs =
    fb_i18n_nl

available_locales = en nl

Automation

If you are fine with the following default values, then you can use the provided justfile with just to automate most of the boring processes:

• Poetry will be used

• The pack will be saved in language-packs/fietsboek-i18n-LOCALE

• The module name will be fietsboek_i18n_LOCALE

just create-language-pack nl
just update-language-pack nl
just compile-language-pack nl