opendev/infra-manual
Code Issues Proposed changes

Merge "Move Translation setup to i18n document"

Browse Source
This commit is contained in:
Zuul 2020-03-11 20:29:06 +00:00 committed by Gerrit Code Review
commit f7ef525e4b
1 changed files with 0 additions and 221 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
doc/source/creators.rst
View File

@ -1114,227 +1114,6 @@ Update the https://docs.openstack.org/ site with links to your project
documentation by following the instructions at `Template generator details
<https://docs.openstack.org/doc-contrib-guide/doc-tools/template-generator.html>`_.
Enabling Translation Infrastructure
===================================
If your project is not an official OpenStack project, skip this section.
Once you have your project set up, you might want to enable
translations. For this, you first need to mark all strings so that
they can be localized, use `oslo.i18n`_ for this and follow the
`guidelines`_.
.. _oslo.i18n: https://docs.openstack.org/oslo.i18n/
.. _guidelines: https://docs.openstack.org/oslo.i18n/latest/user/guidelines.html
Note that this is just enabling translations, the actual translations
are done by the i18n team, and they have to prioritize which projects
to translate.
First enable translation in your project, depending on whether it is a
Django project, a Python project or a ReactJS project.
.. note::
The infra scripts consider a project as a Django project when your repository
name ends with ``-dashboard``, ``-ui``, ``horizon`` or ``django_openstack_auth``.
Otherwise your project will be recognized as a Python project.
If your repository structure is more complex, for example, with multiple
python modules, or with both Django and Python projects, see
:ref:`translation-setup-complex-case` as well.
Python Projects
---------------
Update your ``setup.cfg`` file to include support for translation. It
should contain the ``compile_catalog``, ``update_catalog``, and
``extract_messages`` sections as well as a ``packages`` entry in the
``files`` section:
.. code-block:: ini
[files]
packages = ${MODULENAME}
[compile_catalog]
directory = ${MODULENAME}/locale
domain = ${MODULENAME}
[update_catalog]
domain = ${MODULENAME}
output_dir = ${MODULENAME}/locale
input_file = ${MODULENAME}/locale/${MODULENAME}.pot
[extract_messages]
keywords = _ gettext ngettext l_ lazy_gettext
mapping_file = babel.cfg
output_file = ${MODULENAME}/locale/${MODULENAME}.pot
Replace ``${MODULENAME}`` with the name of your main module like
``nova`` or ``novaclient``. Your i18n setup file, normally named
``_i18n.py``, should use the name of your module as domain name:
.. code-block:: python
_translators = oslo_i18n.TranslatorFactory(domain='${MODULENAME}')
Create file ``babel.cfg`` with the following content:
.. code-block:: ini
[python: **.py]
Django Projects
---------------
Update your ``setup.cfg`` file. It should contain a ``packages`` entry
in the ``files`` section:
.. code-block:: ini
[files]
packages = ${MODULENAME}
Create file ``babel-django.cfg`` with the following content:
.. code-block:: ini
[python: **.py]
[django: **/templates/**.html]
[django: **/templates/**.csv]
Create file ``babel-djangojs.cfg`` with the following content:
.. code-block:: ini
[javascript: **.js]
[angular: **/static/**.html]
ReactJS Projects
----------------
Three new dependencies are required : ``react-intl``,
``babel-plugin-react-intl``, and ``react-intl-po``.
Update your ``package.json`` file. It should contain references to the
``json2pot`` and ``po2json`` commands.
.. code-block:: javascript
"scripts": {
...
"json2pot": "rip json2pot ./i18n/extracted-messages/**/*.json -o ./i18n/messages.pot",
"po2json": "rip po2json -m ./i18n/extracted-messages/**/*.json"
}
The translated PO files will converted into JSON and placed into the
``./i18n/locales`` directory.
Add Translation Server Support
------------------------------
Propose a change to the ``openstack/project-config`` repository
including the following changes:
#. Set up the project on the translation server.
Edit file ``gerrit/projects.yaml`` and add the ``translate``
option:
.. code-block:: yaml
- project: openstack/<projectname>
description: Latest and greatest cloud stuff.
options:
- translate
#. Add the jobs to your pipelines.
Edit file ``zuul.d/projects.yaml`` and add a template which
defines translation jobs to your repository:
.. code-block:: yaml
- project:
name: openstack/<projectname>
templates:
- translation-jobs-master-stable
If the repository is planned to have stable branch, use the
``translation-jobs-master-stable`` template. Otherwise use
the ``translation-jobs-master-only`` template.
When submitting the change to ``openstack/project-config`` for
review, use the ``translation_setup`` topic so it receives the
appropriate attention:
.. code-block:: console
$ git review -t translation_setup
With these changes merged, the strings marked for translation are sent
to the translation server after each merge to your project. Also, a
periodic job is set up that checks daily whether there are translated
strings and proposes them to your project together with translation
source files. Note that the daily job will only propose translated
files where the majority of the strings are translated.
Checking Translation Imports
----------------------------
As a minimal check that the translation files that are imported are
valid, you can add to your lint target (``pep8`` or ``linters``) a
simple ``msgfmt`` test:
.. code-block:: console
$ bash -c "find ${MODULENAME} -type f -regex '.*\.pot?' -print0| \
xargs -0 -n 1 --no-run-if-empty msgfmt --check-format -o /dev/null"
Note that the infra scripts run the same test, so adding it to your
project is optional.
.. _translation-setup-complex-case:
More complex cases
------------------
The infra scripts for translation setup work as follows:
* The infra scripts recognize a project type based on its repository name.
If the repository name ends with ``-dashboard``, ``-ui``, ``horizon``
or ``django_openstack_auth``, it is treated as a Django project.
Otherwise it is treated as a Python project.
* If your repository declares multiple python modules in ``packages`` entry
in ``[files]`` section in ``setup.cfg``, the infra scripts run translation
jobs for each python module.
We strongly recommend to follow the above guideline, but in some cases
this behavior does not satisfy your project structure. For example,
* Your repository contains both Django and Python code.
* Your repository defines multiple python modules, but you just want to
run the translation jobs for specific module(s).
In such cases you can declare how each python module should be handled
manually in ``setup.cfg``. Python modules declared in ``django_modules``
and ``python_modules`` are treated as Django project and Python project
respectively. If ``django_modules`` or ``python_modules`` entry does not
exist, it is interpreted that there are no such modules.
.. code-block:: ini
[openstack_translations]
django_modules = module1
python_modules = module2 module3
You also need to setup your repository following the instruction
for Python and/or Django project above appropriately.
.. _zuul_best_practices:
Zuul Best Practices