Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 69 additions & 1 deletion Translation.md
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The command to build the translated version of the website also needs to be updated. Given we need to preprocess things in conf.py using the value of language we can't use -D anymore. Change:

# from sphinx-build -D language=<language-code> -b html DISCOVER/ DISCOVER/_build/html
# to
WEBSITE_LANGUAGE=<language-code> sphinx-build -b html DISCOVER/ DISCOVER/_build/html

when running sphinx-build first conf.py gets executed and then all the configuration values that have been defined from executing it are passed to the sphinx class that builds the website. -D option modifies the configuration values, but it does so after executing conf.py. This means that things like current_language_name = next((lang['name_local'] for lang in all_languages if lang['code'] == language), language) get executed with language set to the default instead of the variable passed through -D option

Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Replace <language-code> with your target language (e.g., en, fr, de).
Once .po files are updated, compile them to .mo for use in the built documentation:

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

```
After compiling, rebuild the book to see the translations applied:
Expand All @@ -44,4 +44,72 @@ 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:
```sh
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](https://developers.transifex.com/reference/api-authentication) for details.


Get your token from [Transifex Account Settings](https://app.transifex.com/user/settings/api/).


### 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](https://developers.transifex.com/docs/cli) 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](https://developers.transifex.com/docs/cli) setup.