Skip to content

Translation.md

Latest commit

 

History

History
119 lines (80 loc) · 3.69 KB

Translation.md

File metadata and controls

119 lines (80 loc) · 3.69 KB

Managing Translations

To support localization efforts, follow these steps to extract translatable strings and update translations.

Generating .pot Files

To extract translatable text and generate .pot files, run:

sphinx-build -b gettext DISCOVER/ DISCOVER/_build/gettext

This will store extracted strings in .pot files inside DISCOVER/_build/gettext.

Note

We have set gettext_uuid to True which can be slow. The cookbook isn't very large so it will generally not be relevant, but the linked sphinx docs have tips on accelerating that if relevant.

Updating .po Files

To update existing translations, use the following command:

sphinx-intl update -p DISCOVER/_build/gettext -l <language-code>

Replace with your target language (e.g., en, fr, de).

Applying Translations

Once .po files are updated, compile them to .mo for use in the built documentation:

WEBSITE_LANGUAGE=<language-code> sphinx-build -b html DISCOVER/ DISCOVER/_build/html

After compiling, rebuild the book to see the translations applied:

Option 1: Using a Local Server

Run the following command to start a local server:

python -m http.server 8000 --directory DISCOVER/_build/html/

Then, open http://localhost:8000 in your browser.

Option 2: Opening the File Directly

Alternatively, you can open the book directly by navigating to:

DISCOVER/_build/html/index.html

and opening it in your browser.

Note: Contributors working on multilingual support should ensure .po file updates are included in commits.

Translation Workflow with Transifex

We use Transifex to manage translations for the DISCOVER Cookbook. This guide outlines when and how to interact with Transifex during development. You likely won’t need every step each time—focus on the ones relevant to your task.

Step 1: Installing the Transifex CLI

Transifex provides a Go-based CLI for syncing translation files. Follow the (official installation instructions)[https://developers.transifex.com/docs/cli] for your operating system.

Verify installation:

tx --version

Expected output:

TX CLient, version=1.6.x

Step 2: Authenticate with Transifex

To authenticate, create a .transifexrc file in your home directory. Refer to the official authentication guide for details.

Get your token from Transifex Account Settings.

Step 3: Updating .tx/config

The .tx/config file maps source files to Transifex resources. You’ll only need to modify this whenever a new release is made:

Use the CLI to register new resources:

tx add \
  --organization numfocus \
  --project DISCOVER-Cookbook \
  --resource <resource_name> \
  --file-filter locales/<lang>/LC_MESSAGES/<filename>.po \
  --type PO \
  DISCOVER/_build/gettext/<filename>.pot

Refer to the Transifex CLI reference for more information.

Step 4: Pushing Source and Translation Files

Perform the following steps only when a release is made:

  • Regenerate .po files using sphinx-gettext and sphinx-intl.
  • Open a PR with the updated files.
  • Push to Transifex:
tx push -s -t

This uploads both source and translation files.

Step 5: Pulling Translations

To fetch updated translations from Transifex (done manually before publishing):

tx pull -a -m reviewed

Optional: Add Multiple Resources

To add multiplt resorces, use CLI setup.