From 1771f5705ae3b46ba6d548e72984d4634e871da6 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 3 Aug 2018 19:00:25 -0300 Subject: [PATCH 1/6] Documentation for Manage Translations Guide explaining two different flows to manage translation: manual and using Transifex. --- docs/guides/manage-translations.rst | 229 ++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 docs/guides/manage-translations.rst diff --git a/docs/guides/manage-translations.rst b/docs/guides/manage-translations.rst new file mode 100644 index 00000000000..7581621d263 --- /dev/null +++ b/docs/guides/manage-translations.rst @@ -0,0 +1,229 @@ +Manage Translations +=================== + +This guide walks through the process needed to manage translations of your documentation. +Once this work is done, you can setup your project under Read the Docs to build each language of your documentation by reading :doc:`/localization`. + +Overview +-------- + +There are many different ways to manage documentation in multiple languages by using different tools or services. +All of them have their pros and cons depending on the context of your project or organization. + +In this guide we will focus our efforts around two different methods: manual and using Transifex_. + +In both methods, we need to follow these steps to translate our documentation: + +#. Create translatable files (``.pot`` and ``.po`` extensions) from source language +#. Translate the text on those files from source language to target language +#. Build the documentation in *target language* using the translated texts + +Besides these steps, once we have published our first translated version of our documentation, +we will want to keep it updated from the source language. At that time, the workflow would be: + +#. Update our translatable files from source language +#. Translate only *new* and *modified* texts in source language into target language +#. Build the documentation using the most up to date translations + + +Create translatable files +------------------------- + +To generate these ``.pot`` files it's needed to run this command from your ``docs/`` directory: + +.. code-block:: console + + $ sphinx-build -b gettext . _build/gettext + +.. tip:: + + We recommend configuring Sphinx to use :ref:`sphinx:std:confval:gettext_uuid` as ``True`` + and also :ref:`sphinx:std:confval:gettext_compact` as ``False`` to generate ``.pot`` files. + + +This command will leave the generated files under ``_build/gettext``. + + +Translate text from source language +----------------------------------- + +Manually +~~~~~~~~ + +We recommend using `sphinx-intl`_ tool for this workflow. + +.. _sphinx-intl: https://pypi.org/project/sphinx-intl/ + +First, we need to install it: + +.. code-block:: console + + $ pip install sphinx-intl + + +As a second step, we want to create a directory with each translated file per target language +(in this example we are using Spanish/Argentina and Portuguese/Brazil). +This can be achieved with the following command: + +.. code-block:: console + + $ sphinx-intl update -p _build/gettext -l es_AR -l pt_BR + +This command will create a directory structure similar to the following +(with one ``.po`` file per ``.rst`` file in your documentation):: + + locale + ├── es_AR + │ └── LC_MESSAGES + │ └── index.po + └── pt_BR + └── LC_MESSAGES + └── index.po + + +Now, you can just open those ``.po`` files with a text editor and translate them taking care of no breaking the reST notation. +Example: + +.. code-block:: po + + # b8f891b8443f4a45994c9c0a6bec14c3 + #: ../../index.rst:4 + msgid "" + "Read the Docs hosts documentation for the open source community." + "It supports :ref:`Sphinx ` docs written with reStructuredText." + msgstr "" + "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE " + "BY TARGET LANGUAGE :ref:`Sphinx ` FILL HERE." + + +Using Transifex +~~~~~~~~~~~~~~~ + +Transifex_ is a platform that simplifies the manipulation of ``.po`` files and offers many useful features to make the translation process as smooth as possible. +These features includes a great web based UI, `Translation Memory`_, collaborative translation, etc. + +.. _Transifex: https://www.transifex.com/ +.. _Translation Memory: https://docs.transifex.com/setup/translation-memory + +You need to create an account in their service and a new project before start. + +After that, you need to install the `transifex-client`_ tool which will help you in the process to upload source files, update them and also download translated files. +To do this, run this command: + +.. _transifex-client: https://docs.transifex.com/client/introduction + +.. code-block:: console + + $ pip install transifex-client + +After installing it, you need to configure your account. +For this, you need to create an API Token for your user to access this service through the command line. +This can be done under your `User's Settings`_. + +.. _User's Settings: https://www.transifex.com/user/settings/api/ + + +Now, you need to setup it to use this token: + +.. code-block:: console + + $ tx init --token $TOKEN --no-interactive + + +The next step is to map every ``.pot`` file you have created in the previous step to a resource under Transifex. +To achieve this, you need to run this command: + +.. code-block:: console + + $ tx config mapping-bulk --project $TRANSIFEX_PROJECT --file-extension '.pot' --source-file-dir docs/_build/gettext --source-lang en --type PO --expression 'docs/locale//LC_MESSAGES/{filepath}/{filename}.po' --execute + +This command will generate a file at ``.tx/config`` with all the information needed by the ``transifext-client`` tool to keep our translation synchronized. + +Finally, you need to upload these files to Transifex platform so translators can start their work. +To do this, you can run this command: + +.. code-block:: console + + $ tx push --source + + +Now, you can go to your Transifex's project and check that there is one resource per ``.rst`` file of your documentation. + +After the source files are translated using Transifex, you can download the all translations for all the languages by running: + +.. code-block:: console + + $ tx pull --all + +This command will leave the ``.po`` files needed for building the documentation in the target language under ``locale//LC_MESSAGES``. + +.. warning:: + + It's important to use always the same method to translate the documentation and do not mix them. + Otherwise, it's very easy to end up with inconsistent translation or loosing already translated text. + + +Build the documentation in target language +------------------------------------------ + + +Finally, to build our documentation in Spanish(Argentina) we need to tell Sphinx builder the target language with the following command: + +.. code-block:: console + + $ sphinx-build -b html -D language=es_AR . _build/html/es_AR + +.. note:: + + There is no need to create a new ``conf.py`` to redefine the ``language`` for the Spanish version of this documentation. + +After running this command, the Spanish(Argentina) version of your documentation will be under ``_build/html/es_AR``. + + +Summary +------- + +Update sources to be translated +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once we have done changes in our documentation, we want to make these additions/modifications available for translators so they can update it: + +#. Create the ``.pot`` files: + + .. code-block:: console + + $ sphinx-build -b gettext . _build/gettext + + +.. For the manual workflow, we need to run this command + + $ sphinx-intl update -p _build/gettext -l es_AR -l pt_BR + + +#. Push new files to Transifex + + .. code-block:: console + + $ tx push --sources + + +Build documentation from up to date translation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When translators have finished their job, we want to update the documentation by pulling the changes from Transifex: + +#. Pull up to date translations from Transifex: + + .. code-block:: console + + $ tx pull --all + +#. Commit and push these changes to our repo + + .. code-block:: console + + $ git add docs/locale/ + $ git commit -m "Update translations" + $ git push + +The last ``git push`` will trigger a build per translation defined as part of our project under Read the Docs and make it immediately available. From 4242c8b7558000b2559ba9ffbc30f5b1d0a246e0 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 6 Aug 2018 10:48:20 -0300 Subject: [PATCH 2/6] Extend note in localization docs --- docs/localization.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/localization.rst b/docs/localization.rst index a2bb7ecf61d..14caa1e251e 100644 --- a/docs/localization.rst +++ b/docs/localization.rst @@ -51,4 +51,5 @@ It also gets included in the Read the Docs flyout: .. note:: The default language of any CNAME will be the language of the project the Domain object was set on. See :doc:`alternate_domains` for more information. .. note:: You can include multiple translations in the same repository, + with same ``conf.py`` and ``.rst`` files, but each project must specify the language to build for those docs. From d4fbe7eee715315bfb64c51dc472ec8043c518fe Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 6 Aug 2018 10:53:33 -0300 Subject: [PATCH 3/6] Add a note in localization linking the guide to manage translations --- docs/localization.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/localization.rst b/docs/localization.rst index 14caa1e251e..9d25e60d5d2 100644 --- a/docs/localization.rst +++ b/docs/localization.rst @@ -53,3 +53,5 @@ It also gets included in the Read the Docs flyout: .. note:: You can include multiple translations in the same repository, with same ``conf.py`` and ``.rst`` files, but each project must specify the language to build for those docs. + +.. note:: You can read :doc:`guides/manage-translations` to understand the whole process for a documentation with multiples languages in the same repository and how to keep the translations updated on time. From 120ede28910a2e933c1c11fc9e3cf386cda8619e Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 6 Aug 2018 19:10:33 -0300 Subject: [PATCH 4/6] Style and typos --- docs/conf.py | 2 +- docs/guides/manage-translations.rst | 29 ++++++++++++++++++----------- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a489a1d9631..71d66d0a881 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,7 +46,7 @@ default_role = 'obj' intersphinx_mapping = { 'python': ('http://python.readthedocs.io/en/latest/', None), - 'django': ('http://django.readthedocs.io/en/1.8.x/', None), + 'django': ('http://django.readthedocs.io/en/1.9.x/', None), 'sphinx': ('http://sphinx.readthedocs.io/en/latest/', None), } htmlhelp_basename = 'ReadTheDocsdoc' diff --git a/docs/guides/manage-translations.rst b/docs/guides/manage-translations.rst index 7581621d263..e7d622874cb 100644 --- a/docs/guides/manage-translations.rst +++ b/docs/guides/manage-translations.rst @@ -35,10 +35,11 @@ To generate these ``.pot`` files it's needed to run this command from your ``doc $ sphinx-build -b gettext . _build/gettext + .. tip:: - We recommend configuring Sphinx to use :ref:`sphinx:std:confval:gettext_uuid` as ``True`` - and also :ref:`sphinx:std:confval:gettext_compact` as ``False`` to generate ``.pot`` files. + We recommend configuring Sphinx to use :ref:`gettext_uuid ` as ``True`` + and also :ref:`gettext_compact ` as ``False`` to generate ``.pot`` files. This command will leave the generated files under ``_build/gettext``. @@ -54,7 +55,7 @@ We recommend using `sphinx-intl`_ tool for this workflow. .. _sphinx-intl: https://pypi.org/project/sphinx-intl/ -First, we need to install it: +First, you need to install it: .. code-block:: console @@ -135,9 +136,16 @@ To achieve this, you need to run this command: .. code-block:: console - $ tx config mapping-bulk --project $TRANSIFEX_PROJECT --file-extension '.pot' --source-file-dir docs/_build/gettext --source-lang en --type PO --expression 'docs/locale//LC_MESSAGES/{filepath}/{filename}.po' --execute + $ tx config mapping-bulk \ + --project $TRANSIFEX_PROJECT \ + --file-extension '.pot' \ + --source-file-dir docs/_build/gettext \ + --source-lang en \ + --type PO \ + --expression 'docs/locale//LC_MESSAGES/{filepath}/{filename}.po' \ + --execute -This command will generate a file at ``.tx/config`` with all the information needed by the ``transifext-client`` tool to keep our translation synchronized. +This command will generate a file at ``.tx/config`` with all the information needed by the ``transifext-client`` tool to keep your translation synchronized. Finally, you need to upload these files to Transifex platform so translators can start their work. To do this, you can run this command: @@ -148,8 +156,7 @@ To do this, you can run this command: Now, you can go to your Transifex's project and check that there is one resource per ``.rst`` file of your documentation. - -After the source files are translated using Transifex, you can download the all translations for all the languages by running: +After the source files are translated using Transifex, you can download all the translations for all the languages by running: .. code-block:: console @@ -160,7 +167,7 @@ This command will leave the ``.po`` files needed for building the documentation .. warning:: It's important to use always the same method to translate the documentation and do not mix them. - Otherwise, it's very easy to end up with inconsistent translation or loosing already translated text. + Otherwise, it's very easy to end up with inconsistent translations or loosing already translated text. Build the documentation in target language @@ -186,7 +193,7 @@ Summary Update sources to be translated ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once we have done changes in our documentation, we want to make these additions/modifications available for translators so they can update it: +Once you have done changes in your documentation, you may want to make these additions/modifications available for translators so they can update it: #. Create the ``.pot`` files: @@ -210,7 +217,7 @@ Once we have done changes in our documentation, we want to make these additions/ Build documentation from up to date translation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When translators have finished their job, we want to update the documentation by pulling the changes from Transifex: +When translators have finished their job, you may want to update the documentation by pulling the changes from Transifex: #. Pull up to date translations from Transifex: @@ -226,4 +233,4 @@ When translators have finished their job, we want to update the documentation by $ git commit -m "Update translations" $ git push -The last ``git push`` will trigger a build per translation defined as part of our project under Read the Docs and make it immediately available. +The last ``git push`` will trigger a build per translation defined as part of your project under Read the Docs and make it immediately available. From 4a3bfd5a3233199f4c750abf2f917cee72b7d7ad Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 7 Aug 2018 16:29:00 -0300 Subject: [PATCH 5/6] tx config path --- docs/guides/manage-translations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/manage-translations.rst b/docs/guides/manage-translations.rst index e7d622874cb..6d29ae92509 100644 --- a/docs/guides/manage-translations.rst +++ b/docs/guides/manage-translations.rst @@ -142,7 +142,7 @@ To achieve this, you need to run this command: --source-file-dir docs/_build/gettext \ --source-lang en \ --type PO \ - --expression 'docs/locale//LC_MESSAGES/{filepath}/{filename}.po' \ + --expression 'locale//LC_MESSAGES/{filepath}/{filename}.po' \ --execute This command will generate a file at ``.tx/config`` with all the information needed by the ``transifext-client`` tool to keep your translation synchronized. From 30474caff786ac754f3a3668dc5e45c95a4451f4 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 7 Aug 2018 16:29:42 -0300 Subject: [PATCH 6/6] git add path --- docs/guides/manage-translations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/manage-translations.rst b/docs/guides/manage-translations.rst index 6d29ae92509..5be3d08c617 100644 --- a/docs/guides/manage-translations.rst +++ b/docs/guides/manage-translations.rst @@ -229,7 +229,7 @@ When translators have finished their job, you may want to update the documentati .. code-block:: console - $ git add docs/locale/ + $ git add locale/ $ git commit -m "Update translations" $ git push