diff --git a/docs/about/contributing.md b/docs/about/contributing.md index 22648415..4f5c9a95 100644 --- a/docs/about/contributing.md +++ b/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. diff --git a/docs/dev-guide/translations.md b/docs/dev-guide/translations.md index 40c66a2d..80df04b5 100644 --- a/docs/dev-guide/translations.md +++ b/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 `). 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 `). + +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: diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md index d52a39a4..cf0ecf2f 100644 --- a/docs/user-guide/choosing-your-theme.md +++ b/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 diff --git a/mkdocs/themes/mkdocs/locales/tr_TR/LC_MESSAGES/messages.po b/mkdocs/themes/mkdocs/locales/tr/LC_MESSAGES/messages.po similarity index 96% rename from mkdocs/themes/mkdocs/locales/tr_TR/LC_MESSAGES/messages.po rename to mkdocs/themes/mkdocs/locales/tr/LC_MESSAGES/messages.po index ee81dfe0..8d132854 100644 --- a/mkdocs/themes/mkdocs/locales/tr_TR/LC_MESSAGES/messages.po +++ b/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 \n" -"Language: tr_TR\n" -"Language-Team: tr_TR \n" +"Language: tr\n" +"Language-Team: tr \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" - diff --git a/mkdocs/themes/readthedocs/locales/tr_TR/LC_MESSAGES/messages.po b/mkdocs/themes/readthedocs/locales/tr/LC_MESSAGES/messages.po similarity index 96% rename from mkdocs/themes/readthedocs/locales/tr_TR/LC_MESSAGES/messages.po rename to mkdocs/themes/readthedocs/locales/tr/LC_MESSAGES/messages.po index 00dff6e2..dbfe141d 100644 --- a/mkdocs/themes/readthedocs/locales/tr_TR/LC_MESSAGES/messages.po +++ b/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 , 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 \n" -"Language: tr_TR\n" -"Language-Team: tr_TR \n" +"Language: tr\n" +"Language-Team: tr \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" -