1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
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 $PACK_PATH/fb_i18n_nl/locale/nl
Don't forget to adjust the :file:`locale/.../DISPLAY_NAME` file to give your
language pack the correct human-readable representation.
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
|
