From 0c1134e8dd5007bfb3910e9a09efaad6861c6ff2 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Sat, 7 Mar 2020 17:09:39 +0100 Subject: [PATCH] Move Translation setup to i18n document The translation setup is OpenStack specific, move it to the i18n repository. Depends-On: https://review.opendev.org/711826 Change-Id: I5919bb97527f343fbbf7a01e836cbe607f460e35 --- doc/source/creators.rst | 221 ---------------------------------------- 1 file changed, 221 deletions(-) diff --git a/doc/source/creators.rst b/doc/source/creators.rst index ebcb742..e0b96c8 100644 --- a/doc/source/creators.rst +++ b/doc/source/creators.rst @@ -1129,227 +1129,6 @@ Update the https://docs.openstack.org/ site with links to your project documentation by following the instructions at `Template generator details `_. -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/ - 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/ - 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