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.