Generalize tr_TR translations to just tr, explain how to decide this (#3195)

docs/about/contributing.md

@@ -86,11 +86,12 @@ with `{% trans %}` and `{% endtrans %}` tags.
 
 Each time a translatable text placeholder is added, removed or changed in a
 theme template, the theme's Portable Object Template (`pot`) file needs to be
-updated by running the `extract_messages` command. For example, to update the
-`pot` file of the `mkdocs` theme, run the following command:
+updated by running the `extract_messages` command. To update the
+`pot` file for both built-in themes, run these commands:
 
 ```bash
 pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs
+pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs
 ```
 
 The updated `pot` file should be included in a PR with the updated template.

docs/dev-guide/translations.md

@@ -89,15 +89,26 @@ Initializing a catalog consists of running a command which will create a
 directory structure for your desired language and prepare a Portable Object
 (`messages.po`) file derived from the `pot` file of the theme.
 
-Use the `init_catalog` command on each theme's directory and provide the
-appropriate language code (`-l <language>`). For example, to add a translation
-for the Spanish `es` language to the `mkdocs` theme, run the following command:
+Use the `init_catalog` command on each theme's directory and provide the appropriate language code (`-l <language>`).
+
+The language code is almost always just two lowercase letters, such as `sv`, but in some cases it needs to be further disambiguated.
+
+See:
+
+* [Already translated languages for built-in themes](../user-guide/choosing-your-theme.md#mkdocs-locale)
+* [ISO 639 Language List](https://www.localeplanet.com/icu/iso639.html)
+* [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
+
+In particular, the way to know that the `pt` language should be disambiguated as `pt_PT` and `pt_BR` is that the *Language subtag registry* page contains `pt-` if you search for it. Whereas `sv` should remain just `sv`, because that page does *not* contain `sv-`.
+
+So, if we pick `es` (Spanish) as our example language code, to add a translation for it to both built-in themes, run these commands:
 
 ```bash
-pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales --locale es
+pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es
+pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es
 ```
 
-The above command will create the following file structure:
+The above command will create a file structure as follows:
 
 ```text
 mkdocs/themes/mkdocs/locales
@@ -127,11 +138,11 @@ This step should be completed after a theme template have been [updated][update
 themes] for each language that you are comfortable contributing a translation
 for.
 
-To update the `fr` translation catalog of the `mkdocs` theme, use the following
-command:
+To update the `fr` translation catalog of both built-in themes, use the following commands:
 
 ```bash
-pybabel update --ignore-obsolete --update-header-comment --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales --locale fr
+pybabel update --ignore-obsolete --update-header-comment --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr
+pybabel update --ignore-obsolete --update-header-comment --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l fr
 ```
 
 You can now move on to the next step and [add a translation] for every updated
@@ -159,11 +170,12 @@ you'll want to [test your localized theme](#testing-theme-translations).
 ### Testing theme translations
 
 To test a theme with translations, you need to first compile the `messages.po`
-files of your theme into `messages.mo` files. The following command will compile
-the `es` translation for the `mkdocs` theme.
+files of your theme into `messages.mo` files. The following commands will compile
+the `es` translation for both built-in themes:
 
 ```bash
-pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales --locale es
+pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es
+pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -l es
 ```
 
 The above command results in the following file structure:

docs/user-guide/choosing-your-theme.md

@@ -102,7 +102,7 @@ supports the following options:
     ```
 
 *   __`locale`__{ #mkdocs-locale }: The locale (language/location) used to
-    build the theme. If your locale is not yet supported, it will fallback
+    build the theme. If your locale is not yet supported, it will fall back
     to the default.
 
     The following locales are supported by this theme:
@@ -119,7 +119,7 @@ supports the following options:
     * `nn`: Norwegian Nynorsk
     * `pt_BR`: Portuguese (Brazil)
     * `ru`: Russian
-    * `tr_TR`: Turkish (Turkey)
+    * `tr`: Turkish
     * `uk`: Ukrainian
     * `zh_CN`: Simplified Chinese
 
@@ -192,7 +192,7 @@ theme supports the following options:
     page content as you scroll the page. Default: `True`.
 
 *   __`locale`__{ #readthedocs-locale }: The locale (language/location) used to
-    build the theme. If your locale is not yet supported, it will fallback
+    build the theme. If your locale is not yet supported, it will fall back
     to the default.
 
     The following locales are supported by this theme:
@@ -207,7 +207,7 @@ theme supports the following options:
     * `ja`: Japanese
     * `pt_BR`: Portuguese (Brazil)
     * `ru`: Russian
-    * `tr_TR`: Turkish (Turkey)
+    * `tr`: Turkish
     * `uk`: Ukrainian
     * `zh_CN`: Simplified Chinese