Merge pull request #398 from flpm/change-update-translations

docs: change update translation sessions in nox

Author: flpm

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?
 
@@ -340,10 +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.
+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)
 
-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?
-
-```
-
-```
+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).

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,76 +142,110 @@ 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 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="build-languages")
-def build_languages(session):
+@nox.session(name="update-language")
+def update_language(session):
     """
-    Build the translations of the guide for the specified language.
+    Update the translation files (./locales/*/.po) 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.
+    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 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.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-language")
+def build_language(session):
+    """
+    Build the guide for a specific language translation
+
+    For example: nox -s build-language -- es.
+    """
+    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])