Generalize tr_TR translations to just tr, explain how to decide this

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
 

mkdocs/themes/mkdocs/locales/tr_TR/LC_MESSAGES/messages.po → mkdocs/themes/mkdocs/locales/tr/LC_MESSAGES/messages.po

@@ -1,4 +1,4 @@
-# Turkish (Turkey) translations for MkDocs.
+# Turkish translations for MkDocs.
 # Copyright (C) 2022 MkDocs
 # This file is distributed under the same license as the MkDocs project.
 #
@@ -9,8 +9,8 @@ msgstr ""
 "POT-Creation-Date: 2022-08-15 17:05+0200\n"
 "PO-Revision-Date: 2022-08-21 18:58+0300\n"
 "Last-Translator: Mustafa Sami Salt <mss1451@gmail.com>\n"
-"Language: tr_TR\n"
-"Language-Team: tr_TR <LL@li.org>\n"
+"Language: tr\n"
+"Language-Team: tr <LL@li.org>\n"
 "Plural-Forms: nplurals=1; plural=0;\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
@@ -98,4 +98,3 @@ msgstr "Sonuç bulunamadı"
 #: mkdocs/themes/mkdocs/toc.html:3
 msgid "Table of Contents"
 msgstr "İçindekiler"
-

mkdocs/themes/readthedocs/locales/tr_TR/LC_MESSAGES/messages.po → mkdocs/themes/readthedocs/locales/tr/LC_MESSAGES/messages.po

@@ -1,4 +1,4 @@
-# Turkish (Turkey) translations for MkDocs.
+# Turkish translations for MkDocs.
 # Copyright (C) 2022 MkDocs
 # This file is distributed under the same license as the MkDocs project.
 # FIRST AUTHOR <EMAIL@ADDRESS>, 2021.
@@ -10,8 +10,8 @@ msgstr ""
 "POT-Creation-Date: 2022-08-15 17:05+0200\n"
 "PO-Revision-Date: 2022-08-21 18:39+0300\n"
 "Last-Translator: Mustafa Sami Salt <mss1451@gmail.com>\n"
-"Language: tr_TR\n"
-"Language-Team: tr_TR <LL@li.org>\n"
+"Language: tr\n"
+"Language-Team: tr <LL@li.org>\n"
 "Plural-Forms: nplurals=1; plural=0;\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
@@ -106,4 +106,3 @@ msgstr "Belgelerde ara"
 #: mkdocs/themes/readthedocs/versions.html:1
 msgid "Versions"
 msgstr "Sürümler"
-