-
Notifications
You must be signed in to change notification settings - Fork 687
/
i18n.rst
207 lines (156 loc) · 7.9 KB
/
i18n.rst
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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
Internationalization (i18n)
===========================
The code, templates and javascript user visible strings must all be
wrapped with `gettext`_ functions to be substituted at runtime with
the equivalent localized string. These function names are used as
markers to collect the strings to be translated and store them into
the ``securedrop/translations/messages.pot`` file. For each language
to be translated, a directory is created such as
``securedrop/translations/fr_FR`` and populated with files derived
from ``securedrop/translations/messages.pot``, for translators to work
with and for the `gettext`_ substitution at runtime.
The desktop icon are in the
``install_files/ansible-base/roles/tails-config/templates`` directory.
Their labels are collected in the ``desktop.pot`` file and translated
in the corresponding ``.po`` files in the same directory (``fr.po``,
``de.po`` etc.)
The manage.py translate helper
------------------------------
The `pybabel`_ and `gettext`_ command line is wrapped into the
``manage.py translate-messages`` and ``manage.py translate-desktop``
helpers for convenience. It is designed to be used by developers, to
run tests with fixtures and for packaging.
Updating strings to be translated
---------------------------------
After modifying a string in the code, templates, javascript or desktop
labels, the ``securedrop/translations/messages.pot`` files must be
updated by running the following command in ``/vagrant/securedrop``,
in the development virtual machine::
.. code:: sh
make translate
which wraps ``manage.py translate-messages`` and ``manage.py
translate-desktop``. The updated
``securedrop/translations/messages.pot`` and
``install_files/ansible-base/roles/tails-config/templates/desktop.pot``
should then be reviewed and commited. Once merged in develop, the
changes will be visible in the `Weblate`_ web interface used by
translators because it watches the develop branch of the SecureDrop
repository.
Compiling translations
----------------------
`gettext`_ needs a compiled file for each language (the ``*.mo``
files). This can be done by running the following command
in ``/vagrant/securedrop``, in the development virtual machine:
.. code:: sh
./manage.py --verbose translate-messages --compile
For desktop files the compilation phases creates a modified version of
the original file which includes all the translations collected from
the ``.po`` files.
This can be done by running the following command in
``/vagrant/securedrop``, in the development virtual machine::
./manage.py --verbose translate-desktop --compile
Verifying translations
----------------------
After a translation is compiled, the web page in which it shows can be
verified visually by navigating to the corresponding state from
``http://localhost:8080`` for the source interface or
``http://localhost:8081`` for the journalist interface after running
the following:
.. code:: sh
./manage.py run
An easier way is to generate screenshots for each desired language
with:
.. code:: sh
$ export PAGE_LAYOUT_LOCALES=en_US,fr_FR
$ pytest -v --page-layout tests/pages-layout
...
...TestJournalistLayout::test_col_no_documents[en_US] PASSED
...TestJournalistLayout::test_col_no_documents[fr_FR] PASSED
...
.. note:: if unset, PAGE_LAYOUT_LOCALES defaults to en_US
The screenshots for ``fr_FR`` are available in
``securedrop/tests/pages-layout/screenshots/fr_FR`` and the name of
the file can be found in the function that created it in
``securedrop/tests/pages-layout/test_journalist.py`` or
``securedrop/tests/pages-layout/test_source.py``.
Merging translations back to develop
------------------------------------
`Weblate`_ automatically pushes the translations done via the web
interface as a series of commit to the ``i18n`` branch in the `Weblate
SecureDrop branch`_ which is a fork of the ``develop`` branch of the
`SecureDrop git repository`_. These translations need to be submitted
to the ``develop`` branch via pull requests for merge on a regular basis.
.. code:: sh
$ git clone https://github.com/freedomofpress/securedrop
$ cd securedrop
$ git remote add lab http://lab.securedrop.club/bot/securedrop/tree/i18n
$ git fetch lab
$ git checkout -b wip-i18n origin/develop
$ git checkout lab/i18n -- securedrop/translations
$ git add translations
$ vagrant ssh development
$ cd /vagrant/securedrop ; ./manage.py --verbose translate-desktop --compile
$ git commit -m 'sync with weblate' translations
$ git push wip-i18n
Go to https://github.com/freedomofpress/securedrop and propose a pull request.
.. note:: contrary to the applications translations, the desktop
translations are compiled and merged into the
repository. They need to be available in their translated
form when ``securedrop-admin tailsconfig`` is run because
the development environment is not available.
Merging develop into the weblate fork
-------------------------------------
`Weblate`_ works on a long standing fork of the `SecureDrop git
repository`_ and is exclusively responsible for the content of the
``*.pot`` and ``*.po`` files. It needs to merge the content of the
``develop`` branch back into its ``i18n`` branch to be able to extract
from the sources new strings to translate or existing strings that
have been updated.
The translations must be suspended in `Weblate`_ to avoid conflicts.
* Go to the `Weblate commit page for SecureDrop`_
|Weblate commit Lock|
* Click ``Lock``
|Weblate commit Locked|
The ``develop`` branch can now be merged into ``i18n`` as follows:
.. code:: sh
$ git clone https://github.com/freedomofpress/securedrop
$ cd securedrop
$ git remote add lab http://lab.securedrop.club/bot/securedrop/tree/i18n
$ git fetch lab
$ git checkout -b i18n lab/i18n
$ git merge origin/develop
$ ./manage.py translate --extract-update
The ``manage.py`` command examines all the source files, looking for
strings that need to be translated (i.e. gettext('translate me') etc.)
and update the files used by Weblate, removing, updating and inserting
strings to keep them in sync withe the sources. Carefully review the
output of ``git diff``. Check ``messages.pot`` first for updated strings,
looking for formatting problems. Then review the ``messages.po`` of one
existing translation, with a focus on ``fuzzy`` translations. There is
no need to review other translations because they are processed in the
same way. When you are satisfied with the result, it can be merged
with:
.. code:: sh
$ git commit -a -m 'l10n: sync with upstream origin/develop'
$ git push lab i18n
* Go to the `Weblate commit page for SecureDrop`_ and verify the
commit hash matches the last commit of the ``i18n`` branch. This must
happen instantly after the branch is pushed because Weblate is
notified by GitLab via a webhook. If it is different, ask for help.
|Weblate commit Unlock|
`Weblate`_ pushes the translations done via the web interface
to the develop branch in a fork of the `SecureDrop git repository`_.
These commits must be manually cherry-picked and proposed as pull
requests for the `SecureDrop git repository`_.
|Weblate commit Unlocked|
.. _`gettext`: https://www.gnu.org/software/gettext/
.. _`pybabel`: http://babel.pocoo.org/
.. _`Weblate`: http://weblate.securedrop.club/
.. _`SecureDrop git repository`: https://github.com/freedomofpress/securedrop
.. _`Weblate SecureDrop branch`: http://lab.securedrop.club/bot/securedrop/tree/i18n
.. _`patch they contain is unique`: https://git-scm.com/docs/git-patch-id
.. _`Weblate commit page for SecureDrop`: https://weblate.securedrop.club/projects/securedrop/securedrop/#repository
.. |Weblate commit Lock| image:: ../images/weblate/admin-lock.png
.. |Weblate commit Locked| image:: ../images/weblate/admin-locked.png
.. |Weblate commit Unlock| image:: ../images/weblate/admin-unlock.png
.. |Weblate commit Unlocked| image:: ../images/weblate/admin-unlocked.png