Merge branch 'external-languages'

1 files changed, 140 insertions, 0 deletions

diff --git a/doc/developer/language-pack.rst b/doc/developer/language-pack.rst
new file mode 100644
index 0000000..71cf9e8
--- /dev/null
+++ b/doc/developer/language-pack.rst
@@ -0,0 +1,140 @@
+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
+
+Automation
+----------
+
+If you are fine with the following default values, then you can use the
+provided :file:`justfile` with just_ to automate most of the boring processes:
+
+* Poetry will be used
+* The pack will be saved in :file:`language-packs/fietsboek-i18n-LOCALE`
+* The module name will be ``fietsboek_i18n_LOCALE``
+
+.. code-block:: bash
+
+    just create-language-pack nl
+    just update-language-pack nl
+    just compile-language-pack nl
+
+.. _Poetry: https://python-poetry.org/
+.. _Babel: https://babel.pocoo.org/en/latest/index.html
+.. _just: https://github.com/casey/just