diff --git a/Translation.md b/Translation.md index 3f6fea216..77351f4aa 100644 --- a/Translation.md +++ b/Translation.md @@ -23,7 +23,7 @@ Replace 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= -b html DISCOVER/ DISCOVER/_build/html +WEBSITE_LANGUAGE= sphinx-build -b html DISCOVER/ DISCOVER/_build/html ``` After compiling, rebuild the book to see the translations applied: @@ -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 \ + --file-filter locales//LC_MESSAGES/.po \ + --type PO \ + DISCOVER/_build/gettext/.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. \ No newline at end of file