Skip to content

Commit

Permalink
Address review
Browse files Browse the repository at this point in the history
  • Loading branch information
@rmol
rmol committed Mar 16, 2021
1 parent 42b7f7a commit 653e29b
Showing 1 changed file with 46 additions and 38 deletions.
84 changes: 46 additions & 38 deletions docs/development/i18n.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,18 +59,20 @@ files into the corresponding ``*.j2`` file and committed to the
SecureDrop repository. They are then installed when configuring Tails
with the ``tasks/create_desktop_shortcuts.yml`` tasks.

We don't expect translators to deal with all these files directly, of
course. Translation happens on our `Weblate`_ server, which is
configured to use a fork of the main `SecureDrop git repository`_.

At the start of the the release process, the localization manager
collects string changes on the ``develop`` branch and merges them to
the ``i18n`` branch of the ``securedrop-i18n`` repository. The changes
will then appear in Weblate, and translation can begin. Once complete,
the localization manager collects the changes to the PO files on
``securedrop-i18n/i18n`` in a pull request for ``develop``. Once that
pull request is merged, the translations are backported to the release
branch.
We don't expect translators to deal with all these files
directly. Translation happens on our `Weblate`_ server, which is
configured to use a fork of the `main SecureDrop repository`_.

At the start of the :ref:`release process <release_management>`, the
localization manager collects string changes on the ``develop`` branch
in the `main SecureDrop repository`_ and merges them to the ``i18n``
branch of the `securedrop-i18n repository`_. The changes will then
appear in Weblate, and translation can begin. At the end of the
translation period, the localization manager collects the changes to
the PO files on ``securedrop-i18n/i18n`` in a pull request for
``securedrop/develop``. Once that pull request is merged, the
translations are backported to the release branch in the `main
SecureDrop repository`_.

i18n_tool.py
------------
Expand Down Expand Up @@ -105,10 +107,10 @@ to the ``SUPPORTED_LANGUAGES`` variable.
Update strings to be translated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Whenever strings are modified in the SecureDrop source code, templates
or desktop icon labels, the translation files should also be updated
by running ``make translate`` in the root of the SecureDrop working
copy.
Whenever strings are modified in the SecureDrop source, whether in
Python code, HTML templates, or desktop icon labels, the translation
files should also be updated by running ``make translate`` in the root
of the SecureDrop working copy.

The ``translate`` target runs ``i18n_tool.py translate-messages`` and
``i18n_tool.py translate-desktop``, which in turn use ``pybabel
Expand All @@ -129,25 +131,27 @@ looking for problems like:
languages with complex plural forms

Then review the ``messages.po`` of one existing translation, with a
focus on new translations, which are often marked ``fuzzy``. There is
no need to review multiple languages' ``.po`` files because they are
processed in the same way.
focus on new translations, which are often marked `fuzzy
<https://www.gnu.org/software/gettext/manual/html_node/Fuzzy-Entries.html>`__. There
is no need to review multiple languages' ``.po`` files because they
are processed in the same way.

Once you've reviewed the changes, submit them in a pull request for
the ``develop`` branch in the `SecureDrop git repository`_.
the ``develop`` branch in the `main SecureDrop repository`_.

The new source strings will only be visible to translators in
`Weblate`_ after they've been merged to ``develop`` and that branch
has been merged into the Weblate fork. The localization manager does
this at the beginning of our release cycle.
`Weblate`_ after they've been merged to ``securedrop/develop`` and
that branch has been merged into ``securedrop-i18n/i18n``. The
localization manager does this at the beginning of our release cycle.

.. _merge_develop_to_weblate:

Merge develop into the Weblate fork
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1) First make sure the translation files on ``develop`` contain the
latest source strings. Follow the steps under
1) First make sure the translation files on the ``develop`` branch of
the `main SecureDrop repository`_ contain the latest source
strings. Follow the steps under
:ref:`update_strings_to_be_translated`.

2) Then, translation must be suspended in `Weblate`_, and any
Expand All @@ -163,7 +167,8 @@ uncommitted changes committed and pushed, to avoid conflicts:

|Weblate commit Locked|

3) The ``develop`` branch can now be merged into ``i18n``:
3) The ``securedrop/develop`` branch can now be merged into
``securedrop-i18n/i18n``:

.. code:: sh
Expand All @@ -190,10 +195,11 @@ uncommitted changes committed and pushed, to avoid conflicts:
|Weblate commit Unlock|

Translation can now begin. As translators make progress, `Weblate`_
pushes the translations done via the web interface to the
``securedrop-i18n`` fork of the `SecureDrop git repository`_. When the
translation period ends, these commits will be manually cherry-picked
and proposed as pull requests for the `SecureDrop git repository`_.
pushes the translations done via the web interface in commits to the
``i18n`` branch of the `securedrop-i18n repository`_ (a fork of the
`main SecureDrop repository`_). When the translation period ends,
these commits will be collected into a pull request for the `main
SecureDrop repository`_.

|Weblate commit Unlocked|

Expand All @@ -205,13 +211,13 @@ Merge translations back to develop

`Weblate`_ automatically pushes the translations done via the web
interface as a series of commits 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 back to the ``develop`` branch via pull requests. When
you create a branch for this, begin its name with ``i18n-``, as that
prefix triggers special CI tests for translations.
`securedrop-i18n repository`_, which is a fork of the ``develop``
branch of the `main SecureDrop repository`_. These translations need
to be submitted back to the ``securedrop/develop`` branch via pull
requests. When you create a branch for this, begin its name with
``i18n-``, as that prefix triggers special CI tests for translations.

To fetch the latest translations from the ``i18n`` branch into your
To fetch the latest translations from the ``securedrop-i18n/i18n`` branch into your
working copy of the SecureDrop repository, run these commands in your
repo root:

Expand Down Expand Up @@ -383,6 +389,8 @@ If new screenshots were added as part of this run, make sure to associate them
with relevant strings in Weblate, which you can do from the
`screenshots list <https://weblate.securedrop.org/screenshots/securedrop/securedrop/>`__.

.. _release_management:

Release Management
------------------

Expand Down Expand Up @@ -500,8 +508,8 @@ with a release looming, the server can be rebooted.
.. _`.mo`: https://www.gnu.org/software/gettext/manual/gettext.html#MO-Files
.. _`pybabel`: https://babel.pocoo.org/en/latest/
.. _`Weblate`: https://weblate.securedrop.org/
.. _`SecureDrop git repository`: https://github.com/freedomofpress/securedrop
.. _`Weblate SecureDrop branch`: https://github.com/freedomofpress/securedrop-i18n
.. _`main SecureDrop repository`: https://github.com/freedomofpress/securedrop
.. _`securedrop-i18n repository`: https://github.com/freedomofpress/securedrop-i18n
.. _`patch they contain is unique`: https://git-scm.com/docs/git-patch-id
.. _`Weblate commit page for SecureDrop`: https://weblate.securedrop.org/projects/securedrop/securedrop/#information
.. _`Weblate repository page for SecureDrop`: https://weblate.securedrop.org/projects/securedrop/securedrop/#repository
Expand Down

0 comments on commit 653e29b

Please sign in to comment.