Docs: Relabel Localization as Explanation (Diátaxis) (readthedocs#9790)

* Relabel as Explanation, add initial paragraph, move weird note::, remove note:: about Sphinx-only

* Adds some more explanation and change odd section "Single project in another language" (what is Single project?)

* Change headlines

* Add a section "Translation Workflows"

* Make the Sphinx guide much more prominent as a seealso at the top of the subsection

* Update docs/user/localization.rst

Co-authored-by: Eric Holscher <[email protected]>

* Update docs/user/localization.rst

Co-authored-by: Eric Holscher <[email protected]>

Co-authored-by: Eric Holscher <[email protected]>

Author: benjaoming

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
 

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 <https://weblate.org/>`_
+* `Transifex <https://www.transifex.com/>`_
+* `Crowdin <https://crowdin.com/>`_
+
+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.