diff --git a/docs/user/index.rst b/docs/user/index.rst index 379e5e5e5b6..547859fd03e 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -75,6 +75,7 @@ to help you create fantastic documentation for your project. :glob: :caption: Explanation + /localization /choosing-a-site /build-notifications /custom-domains @@ -235,8 +236,6 @@ out of your documentation and Read the Docs. flyout-menu feature-flags - localization - user-defined-redirects automatic-redirects diff --git a/docs/user/localization.rst b/docs/user/localization.rst index 6c97c4caaec..897100fc95a 100644 --- a/docs/user/localization.rst +++ b/docs/user/localization.rst @@ -1,17 +1,26 @@ Localization of Documentation ============================= -.. note:: This feature only applies to Sphinx documentation. We are working to bring it to our other documentation backends. +In this article, we explain high-level approaches to internationalizing and localizing your documentation. -Read the Docs supports hosting your docs in multiple languages. -There are two different things that we support: +By default, Read the Docs assumes that your documentation is or *might become* multilingual one day. +The initial default language is English and +therefore you often see the initial build of your documentation published at ``/en/latest/``, +where the ``/en`` denotes that it's in English. +By having the ``en`` URL component present from the beginning, +you are ready for the eventuality that you would want a second language. -* A single project written in another language -* A project with translations into multiple languages +Read the Docs supports hosting your documentation in multiple languages. +Read below for the various approaches that we support. +.. contents:: + :local: -Single project in another language ----------------------------------- +Projects with one language +-------------------------- + +If your documentation isn't in English (the default), +you should indicate which language you have written it in. It is easy to set the *Language* of your project. On the project *Admin* page (or *Import* page), @@ -22,10 +31,13 @@ The language will be represented in the URL for your project. For example, a project that is in Spanish will have a default URL of ``/es/latest/`` instead of ``/en/latest/``. -.. note:: You must commit the ``.po`` files for Read the Docs to translate your documentation. +Projects with multiple translations (Sphinx-only) +------------------------------------------------- -Project with multiple translations ----------------------------------- +.. seealso:: + + :doc:`guides/manage-translations-sphinx` + Describes the whole process for a documentation with multiples languages in the same repository and how to keep the translations updated on time. This situation is a bit more complicated. To support this, @@ -44,7 +56,7 @@ This has the results of serving: * ``phpmyadmin`` at ``http://phpmyadmin.readthedocs.io/en/latest/`` * ``phpmyadmin-spanish`` at ``http://phpmyadmin.readthedocs.io/es/latest/`` -It also gets included in the Read the Docs flyout: +It also gets included in the Read the Docs :term:`flyout menu`: .. image:: /img/translation_bar.png @@ -57,4 +69,34 @@ It also gets included in the Read the Docs flyout: 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-sphinx` to understand the whole process for a documentation with multiples languages in the same repository and how to keep the translations updated on time. +.. note:: You must commit the ``.po`` files for Read the Docs to translate your documentation. + + +Translation workflows +~~~~~~~~~~~~~~~~~~~~~ + +When you work with translations, +the workflow of your translators becomes a critical component. + +Considerations include: + +* Are your translators able to use a git workflow? For instance, are they able to translate directly via GitHub? +* Do you benefit from machine translation? +* Do you need different roles, for instance do you need translators and editors? +* What is your source language? +* When are your translated versions published? + +By using Sphinx and .po files, +you will be able to automatically synchronize between your documentation source messages on your git platform and your translation platform. + +There are many translation platforms that support this workflow. +These include: + +* `Weblate `_ +* `Transifex `_ +* `Crowdin `_ + +Because Read the Docs builds your git repository, +you can use any of the above solutions. +Any solution that synchronizes your translations with your git repository +will ensure that your translations are automatically published with Read the Docs.