diff options
| -rw-r--r-- | doc/developer.rst | 1 | ||||
| -rw-r--r-- | doc/developer/language-pack.rst | 123 |
2 files changed, 124 insertions, 0 deletions
diff --git a/doc/developer.rst b/doc/developer.rst index 6b99851..b47b0a4 100644 --- a/doc/developer.rst +++ b/doc/developer.rst @@ -6,6 +6,7 @@ Developer Guide :caption: Contents developer/localize + developer/language-pack This guide contains information for developers that want to modify or extend Fietsboek. This includes information on how to localize Fietsboek to new diff --git a/doc/developer/language-pack.rst b/doc/developer/language-pack.rst new file mode 100644 index 0000000..a39617b --- /dev/null +++ b/doc/developer/language-pack.rst @@ -0,0 +1,123 @@ +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 +:doc:`localization <localize>`, 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: + +.. code-block:: bash + + 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: +:file:`~/fb-i18n-nl` and create the basic structure: + +.. code-block:: bash + + 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 :file:`$PACK_PATH/pyproject.toml`: + +.. code-block:: 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: + +.. code-block:: bash + + $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: + +.. code-block:: bash + + cp -rv $FB_PATH/locale/en/html + +Translating & Compiling +----------------------- + +Update the ``messages.po`` file in +:file:`$PACK_PATH/fb_i18n_nl/locale/nl/LC_MESSAGES/messages.po`, as well as the +HTML files in :file:`$PACK_PATH/fb_18n_nl/locale/nl/html`. + +Once the messages have been translated, you can compile the resulting file: + +.. code-block:: bash + + $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: + +.. code-block:: bash + + pip install $PACK_PATH + +And enable it in your settings: + +.. code-block:: ini + + fietsboek.language_packs = + fb_i18n_nl + + available_locales = en nl + +.. _Poetry: https://python-poetry.org/ +.. _Babel: https://babel.pocoo.org/en/latest/index.html |