Docs: Relabel Localization as Explanation (Diátaxis)

docs/user/index.rst

@@ -76,6 +76,7 @@ to help you create fantastic documentation for your project.
    :glob:
    :caption: Explanation
 
+   /localization
    /build-notifications
    /downloadable-documentation
 
@@ -233,8 +234,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,25 @@
 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.
 
+.. contents::
+    :local:
 
-Single project in another language
-----------------------------------
+Single language project
+-----------------------
+
+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 +30,8 @@ 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.
-
-Project with multiple translations
-----------------------------------
+Project with multiple translations (Sphinx)
+-------------------------------------------
 
 This situation is a bit more complicated.
 To support this,
@@ -58,3 +64,5 @@ It also gets included in the Read the Docs flyout:
           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.