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 new file mode 100644 index 00000000000..5be3d08c617 --- /dev/null +++ b/docs/guides/manage-translations.rst @@ -0,0 +1,236 @@ +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:`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``. + + +Translate text from source language +----------------------------------- + +Manually +~~~~~~~~ + +We recommend using `sphinx-intl`_ tool for this workflow. + +.. _sphinx-intl: https://pypi.org/project/sphinx-intl/ + +First, you 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 '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. + +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 all the 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 translations 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 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: + + .. 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, you may 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 locale/ + $ git commit -m "Update translations" + $ git push + +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. diff --git a/docs/localization.rst b/docs/localization.rst index a2bb7ecf61d..9d25e60d5d2 100644 --- a/docs/localization.rst +++ b/docs/localization.rst @@ -51,4 +51,7 @@ 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. + +.. 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.