From 10c57ad8749129cf6dab9ec5842b9bad81ca3cf5 Mon Sep 17 00:00:00 2001 From: Felipe Moreno Date: Tue, 27 Aug 2024 13:33:46 -0400 Subject: [PATCH 1/6] Fix missing quote in documentation.po file --- locales/es/LC_MESSAGES/documentation.po | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/locales/es/LC_MESSAGES/documentation.po b/locales/es/LC_MESSAGES/documentation.po index 1357f888..a94cd7d6 100644 --- a/locales/es/LC_MESSAGES/documentation.po +++ b/locales/es/LC_MESSAGES/documentation.po @@ -95,7 +95,7 @@ msgstr "" "nativa para Sphinx. rST ha sido la sintaxis por defecto para documentación " "durante muchos años. Sin embargo, recientemente myST ha aumentado en popularidad " "para convertirse en la herramienta favorita para documentación gracias a su -flexibilidad." +"flexibilidad." #: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:9 msgid "" From 5139bc7fb062ff3f4c98bfd8f9c5db1453947bd1 Mon Sep 17 00:00:00 2001 From: Felipe Moreno Date: Tue, 27 Aug 2024 13:38:29 -0400 Subject: [PATCH 2/6] Modified update-translations to include only RELEASE_LANGUAGES; added update-language --- noxfile.py | 51 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/noxfile.py b/noxfile.py index 72138ac4..849544ef 100644 --- a/noxfile.py +++ b/noxfile.py @@ -145,18 +145,49 @@ def clean_dir(session): @nox.session(name="update-translations") def update_translations(session): """ - Update the translation files (./locales/*/.po) for all languages translations. + Update the translation files (./locales/*/.po) for languages in RELEASE_LANGUAGES. - Note: this step is important because it makes sure that the translation files are - up to date with the latest changes in the guide. + Note: this step is called in the CI to keep release translations up to date with + the latest changes in the guide. """ - session.install("-e", ".") - session.install("sphinx-intl") - session.log("Updating templates (.pot)") - session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs) - for lang in LANGUAGES: - session.log(f"Updating .po files for [{lang}] translation") - session.run("sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang) + if RELEASE_LANGUAGES: + session.install("-e", ".") + session.install("sphinx-intl") + session.log("Updating templates (.pot)") + session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs) + for lang in RELEASE_LANGUAGES: + session.log(f"Updating .po files for [{lang}] translation") + session.run("sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang) + else: + session.warn("No release languages defined in RELEASE_LANGUAGES") + + +@nox.session(name="update-language") +def update_language(session): + """ + Update the translation files (./locales/*/.po) for a specific language translation. + + Note: this step is used by language coordinators to keep their translation files up to date + with the latest changes in the guide, before the translation is released. + """ + if session.posargs and (lang := session.posargs.pop(0)): + if lang in LANGUAGES: + session.install("-e", ".") + session.install("sphinx-intl") + session.log("Updating templates (.pot)") + session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs) + session.log(f"Updating .po files for [{lang}] translation") + session.run("sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang) + else: + f"[{lang}] locale is not available. Try using:\n\n " + "nox -s docs-live-lang -- LANG\n\n " + f"where LANG is one of: {LANGUAGES}" + else: + session.error( + "Please provide a language using:\n\n " + "nox -s update-language -- LANG\n\n " + f" where LANG is one of: {LANGUAGES}" + ) @nox.session(name="build-languages") From a2a73c47f3eafa1c77859991ae611992e76cbd6e Mon Sep 17 00:00:00 2001 From: Felipe Moreno Date: Thu, 29 Aug 2024 13:21:33 -0400 Subject: [PATCH 3/6] Rename translation session in noxfile.py --- noxfile.py | 91 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 44 deletions(-) diff --git a/noxfile.py b/noxfile.py index 849544ef..1dd89dd8 100644 --- a/noxfile.py +++ b/noxfile.py @@ -55,7 +55,7 @@ def docs(session): session.install("-e", ".") session.run(SPHINX_BUILD, *BUILD_PARAMETERS, SOURCE_DIR, OUTPUT_DIR, *session.posargs) # When building the guide, also build the translations in RELEASE_LANGUAGES - session.notify("build-translations", ['release-build']) + session.notify("build-release-languages", session.posargs) @nox.session(name="docs-test") @@ -69,7 +69,7 @@ def docs_test(session): session.run(SPHINX_BUILD, *BUILD_PARAMETERS, *TEST_PARAMETERS, SOURCE_DIR, OUTPUT_DIR, *session.posargs) # When building the guide with additional parameters, also build the translations in RELEASE_LANGUAGES # with those same parameters. - session.notify("build-translations", ['release-build', *TEST_PARAMETERS]) + session.notify("build-release-languages", [*TEST_PARAMETERS, *session.posargs]) @nox.session(name="docs-live") @@ -142,8 +142,8 @@ def clean_dir(session): pathlib.Path(content).unlink() -@nox.session(name="update-translations") -def update_translations(session): +@nox.session(name="update-release-languages") +def update_release_languages(session): """ Update the translation files (./locales/*/.po) for languages in RELEASE_LANGUAGES. @@ -189,60 +189,63 @@ def update_language(session): f" where LANG is one of: {LANGUAGES}" ) - -@nox.session(name="build-languages") -def build_languages(session): +@nox.session(name="build-language") +def build_language(session): """ - Build the translations of the guide for the specified language. + Build the guide for a specific language translation - Note: This sessions expects a list of languages to build in the first position of the session arguments. - It does not need to be called directly, it is started by build_translations session. + For example: nox -s build-language -- es. """ - if not session.posargs: - session.error("Please provide the list of languages to build the translation for") - languages_to_build = session.posargs.pop(0) + if session.posargs and (lang := session.posargs.pop(0)): + if lang in LANGUAGES: + session.install("-e", ".") + session.log(f"Building [{lang}] guide") + session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs) + else: + session.error(f"Language {lang} is not in LANGUAGES list.") + else: + session.error( + "Please provide a language using:\n\n " + "nox -s build-language -- LANG\n\n " + f" where LANG is one of: {LANGUAGES}" + ) + +@nox.session(name="build-release-languages") +def build_release_languages(session): + """ + Build the translations of the guide for the languages in RELEASE_LANGUAGES. + """ + if not RELEASE_LANGUAGES: + session.warn("No release languages defined in RELEASE_LANGUAGES") + return session.install("-e", ".") - for lang in languages_to_build: - if lang not in LANGUAGES: - session.warn(f"Language [{lang}] is not available for translation") - continue + for lang in RELEASE_LANGUAGES: session.log(f"Building [{lang}] guide") session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs) + session.log(f"Translations built for {RELEASE_LANGUAGES}") - -@nox.session(name="build-translations") -def build_translations(session): +@nox.session(name="build-all-languages") +def build_all_languages(session): """ - Build translations of the guide. - - Note: this session can be called directly to build all available translations (defined in LANGUAGES). - It is also called by the docs and docs-test sessions with 'release-build' as the first positional - argument, to build only the translations defined in RELEASE_LANGUAGES. + Build the translations of the guide for the languages in LANGUAGES. """ - release_build = False - if session.posargs and session.posargs[0] == 'release-build': - session.posargs.pop(0) - release_build = True - # if running from the docs or docs-test sessions, build only release languages - BUILD_LANGUAGES = RELEASE_LANGUAGES if release_build else LANGUAGES - # only build languages that have a locale folder - BUILD_LANGUAGES = [lang for lang in BUILD_LANGUAGES if (TRANSLATION_LOCALES_DIR / lang).exists()] - session.log(f"Declared languages: {LANGUAGES}") - session.log(f"Release languages: {RELEASE_LANGUAGES}") - session.log(f"Building languages{' for release' if release_build else ''}: {BUILD_LANGUAGES}") - if not BUILD_LANGUAGES: - session.warn("No translations to build") - else: - session.notify("build-languages", [BUILD_LANGUAGES, *session.posargs]) + if not LANGUAGES: + session.warn("No languages defined in LANGUAGES") + return + session.install("-e", ".") + for lang in LANGUAGES: + session.log(f"Building [{lang}] guide") + session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs) + session.log(f"Translations built for {LANGUAGES}") -@nox.session(name="build-translations-test") -def build_translations_test(session): +@nox.session(name="build-all-languages-test") +def build_all_languages_test(session): """ - Build all translations of the guide with testing parameters. + Build all translations of the guide with the testing parameters. This is a convenience session to test the build of all translations with the testing parameters in the same way docs-test does for the English version. """ - session.notify("build-translations", [*TEST_PARAMETERS]) + session.notify("build-all-languages", [*TEST_PARAMETERS]) From 6d0ae874d2bdc8782eb595485e906102184000ba Mon Sep 17 00:00:00 2001 From: Felipe Moreno Date: Sat, 21 Sep 2024 13:04:37 -0400 Subject: [PATCH 4/6] Updated the contributor translation guide --- TRANSLATING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/TRANSLATING.md b/TRANSLATING.md index f319d3a2..e909c18b 100644 --- a/TRANSLATING.md +++ b/TRANSLATING.md @@ -72,10 +72,10 @@ You can find a list of the two-letter Sphinx language option [here](https://www. The translation files contain the original English text and a space for you to enter the translated text. Before starting to translate, you need to make sure the translation files are up to date with the latest changes to the guide. -You can do this by running the following command: +You can do this by running the following command, replacing LANG by the language code you plan to work on (e.g., `es` for Spanish): ```shell -$ nox -s update-translations +$ nox -s update-language -- LANG ``` This command will create the translation files if they don't exist yet, or update them with the latest changes if they already exist. @@ -220,10 +220,10 @@ When working on a translation, you **should not** modify the original English te ## Building the Translated Documentation -Once you finished translating or when you want to check the translation in context, you can build the guide locally on your computer, using the following command: +Once you finished translating or when you want to check the translation in context, you can build the guide locally on your computer, using the following command, replacing LANG by the proper language code (e.g., `es` for Spanish) ```shell -nox -s build-translations +nox -s build-language -- LANG ``` This command will build all the translated versions of the guide defined in the `LANGUAGES` list in `noxfile.py`. These translations will be stored in the `_build/html`, in folders named after the language code (e.g., `es`, `fr`, etc.). @@ -251,7 +251,7 @@ You can follow these steps: 1. Build the translations of the guide with same parameters that will be used during the release: ```shell -nox -s build-translations-test +nox -s build-all-languages-test ``` 2. Make sure there are no warnings or errors in the output. If there are, you will need to fix them before submitting the PR. @@ -297,7 +297,7 @@ When you run the `sphinx-intl stat` command, you will see a list of `.po` files ### What happens when a string has changed in the original English text? -If a string has changed in the original English version, it will be marked as `fuzzy` in the translation file the next time it is updated (`nox -s update-translations`). Contributors working on the translation can then review the fuzzy entries and make the necessary changes to ensure it is accurate, before removing the `fuzzy` tag. +If a string has changed in the original English version, it will be marked as `fuzzy` in the translation file the next time it is updated (`update-language`, `update-all-languages`, or `update-all-release-languages`). Contributors working on the translation can then review the fuzzy entries and make the necessary changes to ensure it is accurate, before removing the `fuzzy` tag. ### How do I handle links in the translated text? From 1c937acf5d09b3a24cbfbb4237a82cff44901c95 Mon Sep 17 00:00:00 2001 From: Felipe Moreno Date: Sat, 21 Sep 2024 13:18:10 -0400 Subject: [PATCH 5/6] Mention discord in section about getting help --- TRANSLATING.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/TRANSLATING.md b/TRANSLATING.md index e909c18b..43af5e01 100644 --- a/TRANSLATING.md +++ b/TRANSLATING.md @@ -340,10 +340,4 @@ TODO: There are many approaches here, some projects release a translation as soo ### How can I get help with my translation? -If you have any questions or need help with your translation, you can create an issue in the repository. - -TODO: Maybe [Discourse](https://pyopensci.discourse.group/) could be used as a way for contributors to ask for help with translations or the translation workflow? - -``` - -``` +If you have any questions or need help with your translation, you can create an issue in the repository. You can also join the PyOpenSci Discord and ask questions in the translation channel! TODO: Add more information about how to find PyOpenSci in Discord. From 6680f281674ed8165eb01fa79f03f0f6a557a4a2 Mon Sep 17 00:00:00 2001 From: Felipe Moreno Date: Mon, 23 Sep 2024 16:14:44 -0400 Subject: [PATCH 6/6] Added information about discord to Translation Guide FAQ --- TRANSLATING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/TRANSLATING.md b/TRANSLATING.md index 43af5e01..c8f6c62a 100644 --- a/TRANSLATING.md +++ b/TRANSLATING.md @@ -340,4 +340,6 @@ TODO: There are many approaches here, some projects release a translation as soo ### How can I get help with my translation? -If you have any questions or need help with your translation, you can create an issue in the repository. You can also join the PyOpenSci Discord and ask questions in the translation channel! TODO: Add more information about how to find PyOpenSci in Discord. +If you have any questions or need help with your translation, you can create an [issue](https://github.com/pyOpenSci/python-package-guide/issues) in the [Packaging Guide repository](https://github.com/pyOpenSci/python-package-guide) + +You can also ask in the PyOpenSci Discord server ([click here](https://discord.gg/CvSMp4zcqX) to join), you will find a general channel for questions related to our workflow, processes, and tools (translation-general) and channels for each of the languages we are working on (spanish-translation, japanese-translation, etc).