Add Transifex setup guide for maintainers in `Translation.md` #371

speco29 · 2025-08-07T18:19:41Z

Description of Changes

@OriolAbril @kamila-NF
Narrates how can maintainers setup the CLI setup of Transifex and push and pull Translations

Related Issue

Type of Change

Please check the appropriate box that describes your PR:

🐛 Bug Fix — Fixes a documented issue or incorrect behavior
✨ Content Enhancement — Updates or improves existing content
✍️ New Content — Adds new chapters, examples, or significant sections
🛠️ Other — Please describe in the Description of Changes section

Additional Notes (Optional)

Checklist

I have searched open pull requests to avoid duplicates.
I have built the book locally using the build instructions and verified my changes work as expected.
I have written clear, conventional commit messages, as per the Pull Request Guidelines.

…R-Cookbook into translation-docs

netlify · 2025-08-07T18:19:47Z

✅ Deploy Preview for stupendous-kringle-a86e81 ready!

Name	Link
🔨 Latest commit	`00cf9ac`
🔍 Latest deploy log	https://app.netlify.com/projects/stupendous-kringle-a86e81/deploys/68ad9dc0bf859100085ef89f
😎 Deploy Preview	https://deploy-preview-371--stupendous-kringle-a86e81.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

OriolAbril · 2025-08-12T16:40:51Z

Translation.md

+Download the latest Go-based CLI from the [Transifex CLI releases](https://github.com/transifex/cli/releases).
+
+Place the binary in a folder like ```C:\tx-cli``` and add it to your system’s PATH.


Link to the transifex website for the install instructions. Copying these over here makes them windows only and they could also become outdated more easily. I would instead link to the transifex instructions and then show how to verify the install was successful

I have made the changes, you can review it;)

OriolAbril · 2025-08-12T16:48:07Z

Translation.md

+
+## Syncing with Transifex
+
+We use Transifex as our translation service for the Cookbook, in order to collaborate on translations via Transifex, follow these steps:


I would restrucuture the wording and sections around this. I think the vast majority of cases will/should not follow all these steps. I would instead focus on what each step does and when it should be executed. i.e. when a new page/chapter is added to the cookbook we need to add it to .tx/config, when we do any update to the content we need to regenerate source files via sphinx gettext and sphinx-intl then both open a PR with that and push to transifex (that includes the previous case when a new chapter is added but also updates to existing chapters), then at some other point (iiuc 100% manually) we need to pull translations from transifex so they make it into the published website

OriolAbril · 2025-08-12T16:48:50Z

Translation.md

+
+### Step 2: Authenticate with Transifex
+
+Create a ```.transifexrc``` file in your home directory ```(C:\Users\<yourname>\)``` with:


also link to the official documentation on authenticating

OriolAbril · 2025-08-12T16:56:41Z

Translation.md

+Get your token from [Transifex Account Settings](https://app.transifex.com/user/settings/api/).
+
+
+### Step 3: Configure ```.tx/config```


I don't think is will be needed ever again, covering adding more resources or deleting resources from it is probably fine. Again, I'd recommend using tx client for adding/deleting, and linking to the official docs even if we add the command in here.

OriolAbril · 2025-08-12T16:58:08Z

Translation.md

+To upload updated source files to Transifex:
+```
+tx push -s
+```
+
+To push translation files:
+```
+tx push -t
+```


I can't come up with any scenario where we'd want one of those but not the other. Can we use tx push -s -t all at once? Or explain when we'd want to use one without the other?

OriolAbril · 2025-08-12T17:02:34Z

Translation.md

+- Run ```tx status``` to check resource sync.
+- Use ```tx config discovery``` to auto-detect new files.
+
+### Need help? Reach out to the maintainers or open an issue!


The target audience for this document will be the ones that will know the most about transifex and translations. I am not sure this is helpful in this situation

I think this is useful

OriolAbril · 2025-08-12T17:08:53Z

Translation.md

+### Step 5: Pull Translations
+To download all available translations:
+```
+tx pull -a


I am adding translations on transifex right now and will review some but not others. Please make sure the command we add here pulls only reviewed translations but not translated but unreviewed content.

I have added 4 translated+reviewed strings and 4 translated but not reviewed (the content of those strings says in English "This string is translated but not reviewed and should not be pulled from transifex") so you can easily check which way of pulling gets only reviewed content.

I will check this

kamilastep · 2025-08-15T20:41:43Z

I'm not sure what should I test here.

OriolAbril · 2025-08-26T11:18:25Z

Translation.md

+### Step 5: Pulling Translations
+To fetch updated translations from Transifex (done manually before publishing):
+```
+tx pull -a


I tested this command in #368 and it downloads unreviewed translations. It needs to be:

Suggested change

tx pull -a

tx pull -a -m reviewed

OriolAbril · 2025-08-26T11:20:24Z

Translation.md

+After updating content or adding new chapters:
+- Regenerate ```.po``` files using ```sphinx-gettext``` and ```sphinx-intl```.
+- Open a PR with the updated files.
+- Push to Transifex:


at the call after @kamila-NF feedback we decided to do these steps only when a release is made, not every time a change is made

OriolAbril · 2025-08-26T11:20:42Z

Translation.md

+- Adding a new chapter or page to the Cookbook
+- Removing or renaming existing translation files


at the call after @kamila-NF feedback we decided to do these steps only when a release is made, not every time a change is made

OriolAbril · 2025-08-26T11:25:36Z

Translation.md

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

Translation.md

speco29 · 2025-08-27T14:44:40Z

@OriolAbril I have made the changes you suggested, is their anything else to change/add?

OriolAbril

looks good, leaving it up for @kamila-NF, @aterrel or @emmasaroyan to click merge after another quick review on their end

speco29 added 8 commits July 27, 2025 00:24

Set up Transifex integration for translations

f033f1a

updation

23544d6

Merge branch 'translation-docs' of https://github.com/speco29/DISCOVE…

1d9f8dc

…R-Cookbook into translation-docs

updating translation.md

e9149ce

updating content and deleting files

4daee72

Merge branch 'numfocus:main' into translation-docs

171b025

add transifex setup for maintainers in Translation.md

0954db5

Merge branch 'translation-docs' of https://github.com/speco29/DISCOVE…

0919220

…R-Cookbook into translation-docs

Update Translation.md

715c64c

OriolAbril reviewed Aug 12, 2025

View reviewed changes

speco29 added 3 commits August 13, 2025 15:46

updated the Translation.md according to feedback

d630a59

update the guide according to feedback

8220d2c

update the guide according to feedback

8186cf6

speco29 changed the title ~~Add Transifex setup for maintainers in Translation.md~~ Add Transifex setup guide for maintainers in Translation.md Aug 21, 2025

speco29 added 2 commits August 21, 2025 19:34

remooves the locales/en and updates the guide

217f474

changes the file type from PO to markdown

a921a07

OriolAbril reviewed Aug 26, 2025

View reviewed changes

OriolAbril mentioned this pull request Aug 26, 2025

Add transifex setup to 2.0 release #368

Merged

7 tasks

updates the file according to feedback

00cf9ac

speco29 marked this pull request as ready for review August 26, 2025 17:17

OriolAbril reviewed Aug 31, 2025

View reviewed changes

OriolAbril approved these changes Sep 11, 2025

View reviewed changes

OriolAbril merged commit 8dc48e8 into numfocus:main Sep 11, 2025
4 checks passed

		Download the latest Go-based CLI from the [Transifex CLI releases](https://github.com/transifex/cli/releases).

		Place the binary in a folder like ```C:\tx-cli``` and add it to your system’s PATH.


		## Syncing with Transifex

		We use Transifex as our translation service for the Cookbook, in order to collaborate on translations via Transifex, follow these steps:


		### Step 2: Authenticate with Transifex

		Create a ```.transifexrc``` file in your home directory ```(C:\Users\<yourname>\)``` with:

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


		### Step 3: Configure ```.tx/config```

		- Adding a new chapter or page to the Cookbook
		- Removing or renaming existing translation files

Uh oh!

Add Transifex setup guide for maintainers in Translation.md #371

Add Transifex setup guide for maintainers in Translation.md #371

Uh oh!

Conversation

speco29 commented Aug 7, 2025 • edited by emmasaroyan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Changes

Related Issue

Type of Change

Additional Notes (Optional)

Checklist

Uh oh!

netlify bot commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for stupendous-kringle-a86e81 ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kamilastep commented Aug 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

speco29 commented Aug 27, 2025

Uh oh!

OriolAbril left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Add Transifex setup guide for maintainers in `Translation.md` #371

Add Transifex setup guide for maintainers in `Translation.md` #371

speco29 commented Aug 7, 2025 •

edited by emmasaroyan

Loading

netlify bot commented Aug 7, 2025 •

edited

Loading