Skip to content

Commit

Permalink
Merge pull request #398 from flpm/change-update-translations
Browse files Browse the repository at this point in the history 
docs: change update translation sessions in nox
  • Loading branch information
@flpm
flpm committed Sep 24, 2024
2 parents 41866f9 + a19d40c commit cdbdf85
Show file tree
Hide file tree
Showing 2 changed files with 95 additions and 65 deletions.
20 changes: 8 additions & 12 deletions TRANSLATING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.).
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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?

Expand Down Expand Up @@ -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).
140 changes: 87 additions & 53 deletions noxfile.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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")
Expand Down Expand Up @@ -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])

0 comments on commit cdbdf85

Please sign in to comment.