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
|
Localizing Fietsboek
====================
Most of the localization in Fietsboek is done using the `gettext
<https://www.gnu.org/software/gettext/>`__ machinery to provide translated
messages. Additionally, `Babel <https://babel.pocoo.org/en/latest/>`__ is used
to provide localized number and date formatting.
In addition to ``gettext``-based messages, some longer texts are also provided
as stand-alone files in their respective language directories.
The ``gettext`` Machinery
-------------------------
The ``gettext`` machinery depends on three files:
The ``.pot`` files are the template files that contain all the messages that
need to be translated. They are generated by walking through the source code
and finding marked translation strings.
The ``.po`` files are translations, initialized from the ``.pot`` template. For
every language, a ``.po`` file contains the translated messages and can be
edited by the translator.
Finally, the ``.mo`` files are compiled versions of the ``.po`` files, intended
to be more efficient.
Extracting Messages
-------------------
.. note::
This section can be skipped if you only intend on creating a new
translation. It is only important if you introduce new features with new
messages to the code.
If you introduce new messages in Fietsboek, it is important to regenerate the
``.pot`` template. Only then can translations for your messages be added.
In order to do so, use the :program:`pybabel` binary:
.. code:: bash
.venv/bin/pybabel extract -F babel.cfg -o fietsboek/locale/fietslog.pot --input-dirs=fietsboek
The :file:`justfile` (requires just_) contains a shortcut for this command:
.. code:: bash
just extract-messages
Creating a New Language
-----------------------
If you want to add a translation for a language that does not yet exist, first
generate the ``.po`` file containing the messages using :program:`pybabel`:
.. code:: bash
# Replace LOCALE with the locale name, for example "nl" or "fr"
.venv/bin/pybabel init -d fietsboek/locale -l LOCALE -i fietsboek/locale/fietslog.pot
This will create the directory :file:`fietsboek/locale/{language}`.
Finally, you need to copy the non-gettext messages. This is best done by
copying over the english original texts:
.. code:: bash
# Replace nl with the locale that you just generated
cp -r fietsboek/locale/en/html fietsboek/locale/nl/
Again, there is a shortcut in the :file:`justfile` that does both steps:
.. code:: bash
just init-language nl
Updating a Language
-------------------
When features and messages get added to Fietsboek, it is important to keep the
message catalogues up to date:
.. code:: bash
# Replace nl with the locale that you want to update
.venv/bin/pybabel update -d fietsboek/locale -l nl -i fietsboek/locale/fietslog.pot
This ensures that every message from the template is also present in the
language's message catalogue, ready for translation.
Alternatively, you can also use the shortcut again:
.. code:: bash
just update-language nl
Translating
-----------
Once you have the ``.po`` file generated (either by initializing a new language
or by updating an existing one), it is time to actually translate messages.
This is done by editing the
:file:`fietsboek/locale/{language}/LC_MESSAGES/messages.po` file. This can be
done either by using a standard text editor, or by using a specialized tool
like :program:`poedit`.
After translating the messages, the files in
:file:`fietsboek/locale/{language}/html` should also be translated. For this, a
text editor or a HTML editor can be used.
Compiling the Messages
----------------------
To generate the machine readable message format, the message catalogue has to
be compiled:
.. code:: bash
# Replace nl with the locale that you want to compile
.venv/bin/pybabel compile -d fietsboek/locale -l nl -i fietsboek/locale/nl/LC_MESSAGES/messages.po
Or using the shortcut:
.. code:: bash
just compile-language nl
Further Reading
---------------
* The Pyramid documentation: `Internationalization and Localization
<https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/i18n.html>`__
.. _just: https://github.com/casey/just
|
