Skip to content

build: extract translations per xblock for openedx-translations - #329

Open
farhan wants to merge 3 commits into
mainfrom
farhan/extract-translations-per-block
Open

farhan wants to merge 3 commits into
mainfrom
farhan/extract-translations-per-block

Conversation

@farhan

@farhan farhan commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Ticket: Closes xblocks-core#242 (epic: xblocks-core#241)

This follows the same approach as xblocks-extra#35. The companion PR is openedx-translations#85196, and the docs update is xblocks-core#331.

Summary

openedx-platform looks up XBlock translations by module name (i18n_api.py), so it can't match the old single combined catalog to the blocks.

  • make extract_translations now writes one django.po per block to xblock_<name>/conf/locale/en/LC_MESSAGES/ at the repo root.
  • The compile, dummy, validate, pull, push and Transifex client targets are removed, along with the translations tox env. They relied on the old text.po layout, and no CI workflow runs them.
  • extract_translations now stops and exits non-zero if any block fails, so the daily job can't commit a partial set of source files.
  • .gitignore: *.po → **/conf/locale/**/LC_MESSAGES/*.
  • Each block's conf/locale/config.yaml now lists only the source locale (en), matching openedx-platform and xblocks-extra. dummy_locales is removed because nothing reads it.
  • xblock_pdf gets conf/locale/config.yaml and __init__.py. Without them, extraction skipped it.

Translation flow

This is the OEP-58 flow, as described in Enabling Translations on a New Repo:

  1. Extract: The daily extract-translation-source-files.yml workflow clones this repo and runs make extract_translations. Its python-monorepo job then commits each block's source file to translations/xblocks-core/xblock_<name>/conf/locale/en/.
  2. Translate: The Transifex GitHub App uploads each block as a separate resource listed in transifex.yml. It then opens PRs with the reviewed translations.
  3. Pull: In openedx-platform, make pull_xblock_translations runs atlas with translations/*/<module_name>/conf/locale:<module_name> for each installed XBlock and compiles the result.

For example, Arabic for the problem block lands at:

translations/xblocks-core/xblock_problem/conf/locale/ar/LC_MESSAGES/django.po

⚠️ Caution: built-in block fallback

The extracted blocks show translated strings today only because of a fallback. Their own catalog is missing, so Django uses the edx-platform catalog, which still has the same msgids from the built-in xmodule blocks (see xblocks-core#241).

  • No legacy per-block directories need to be deleted in openedx-translations. The module names also differ (xblock_problem vs xmodule), so the atlas glob clash fixed in openedx-translations#73194 doesn't apply.
  • Don't remove the built-in blocks from openedx-platform until both of these are done. Otherwise their translations disappear.
    1. The xblocks-core catalogs are published and confirmed working. That means the xblock_* catalogs exist in openedx-translations, and make pull_xblock_translations (in lms-shell) produces non-empty ar/es_419 catalogs for them.
    2. xblocks-core#332 is fixed. Some strings skip the block's i18n service and are still read from the platform catalog: the Video, Problem and Annotatable JS (no block defines i18n_js_namespace), xblock_problem/capa/safe_exec/remote_exec.py and LTI's lti_form.html. A per-block catalog doesn't cover them.

How to test

  1. Run uv run --with edx-i18n-tools make extract_translations. This needs GNU gettext.
  2. Confirm that 9 files exist at xblock_*/conf/locale/en/LC_MESSAGES/django.po.
  3. Confirm that uv run --with edx-i18n-tools django-admin compilemessages --locale en succeeds.

Local result: all 9 blocks were extracted (xblock_problem 215 msgids, xblock_discussion 131, xblock_video 129, …), and compilation succeeded.

🤖 Generated with Claude Code

openedx-platform looks up xblock translations by module name
(translations/*/<module_name>/conf/locale), so a single combined
catalog can't be matched to the blocks. Write one django.po per
block under <module_name>/conf/locale/ instead, mirroring
openedx/xblocks-extra#35.

The compile/dummy/validate/pull/push targets and the translations
tox env relied on the old src/ text.po layout, so they are removed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Extraction only needs conf/locale/, and OEP-58 syncs through the
Transifex GitHub App, so the client .tx/config (which pointed at the
no-longer-produced text.po) is not needed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@farhan
farhan marked this pull request as ready for review November 16, 2026 10:41

@irfanuddinahmad irfanuddinahmad left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The per-block layout looks right to me: xblock_<name>/conf/locale matches the platform's atlas lookup translations/*/{module_name}/conf/locale.

Some strings will still be read from the platform catalog. The per-block catalog is only used through the block's i18n service. Strings that skip it go to Django's global catalog, which only has msgids from openedx-platform's own source:

  • JS. No block defines i18n_js_namespace, so compile_xblock_js_messages (xblock_django/translation.py) never compiles a JS catalog for them, and the blocks' JS calls the global gettext(). Video, Problem and Annotatable JS is translated today only because the platform's djangojs catalog still has the same msgids from xmodule/js/src/. Those copies go away with the built-in blocks.
  • Python and templates (smaller). xblock_problem/capa/safe_exec/remote_exec.py calls Django's gettext directly. LTI's lti_form.html is rendered without i18n_service.

The fix (i18n_js_namespace plus namespaced JS calls, and the i18n service at those two spots) is block code, so I've opened #332 to track it outside this PR.

What counts as "confirmed working"? I'd suggest: the xblock_* catalogs exist in openedx-translations, and pull_xblock_translations produces non-empty ar/es_419 catalogs for them.

Generated using Claude Code

Comment thread Makefile Outdated
echo "Extracting translations for $$xblock..."; \
module_name=$$(basename $$xblock); \
echo "Extracting translations for $$module_name..."; \
cd $$xblock && i18n_tool extract --no-segment; \

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

If i18n_tool extract fails for one block, the loop carries on and make exits 0, so the daily openedx-translations job could commit a partial set of source files. Maybe cd $$xblock && i18n_tool extract --no-segment || exit 1; \?

Generated using Claude Code

The loop ran as one shell command whose exit code came from its last
statement, so a failed i18n_tool, msgcat or mv was swallowed and make
exited 0. The daily openedx-translations job could then commit a
partial set of source files. Run the loop under set -e, with each
step as its own statement so set -e catches it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
farhan added a commit to openedx/xblocks-extra that referenced this pull request Nov 17, 2026
The loop ran as one shell command whose exit code came from its last
statement, so a failed i18n_tool, msgcat or mv was swallowed and make
exited 0. The daily openedx-translations job could then commit a
partial set of source files. Run the loop under set -e, with each
step as its own statement so set -e catches it. Same fix as
openedx/xblocks-core#329.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@farhan

farhan commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

@irfanuddinahmad this is ready for a second pass. Your comment on the extract loop is fixed in cba03eb, and all checks are green.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Implement localization | xblocks-contrib

2 participants