From c593f94d2b857dbab12f6a76d209f4c5f29cb23e Mon Sep 17 00:00:00 2001 From: farhan Date: Mon, 16 Nov 2026 15:16:47 +0500 Subject: [PATCH] docs: describe the per-xblock translation extraction The README and i18n docs still described the combined catalog and the compile, dummy, validate and Transifex targets, which openedx/xblocks-core#329 removes. Co-Authored-By: Claude Opus 5.5 --- README.rst | 113 +++++----------------------------- docs/internationalization.rst | 57 +++-------------- 2 files changed, 23 insertions(+), 147 deletions(-) diff --git a/README.rst b/README.rst index 6790bc3a..da4c0191 100644 --- a/README.rst +++ b/README.rst @@ -94,10 +94,9 @@ Localization (l10n) is adapting a program to local language and cultural habits. For information on how to enable translations, visit the `Open edX XBlock tutorial on Internationalization `_. -The included Makefile contains targets for extracting, compiling and validating translatable strings. +The included Makefile contains a target for extracting translatable strings. Each XBlock in this repository has its own translation configuration under -``src/xblock_/conf/locale/`` and its own Transifex resource mapping under -``src/xblock_/.tx/config``. All Make targets iterate over every XBlock automatically. +``src/xblock_/conf/locale/``. The Make target iterates over every XBlock automatically. The general steps to provide multilingual messages for a Python program (or an XBlock) are: @@ -153,19 +152,15 @@ This iterates over every XBlock and: 1. Runs ``i18n_tool extract --no-segment`` to extract Python, HTML and JS strings. 2. Merges ``djangojs.po`` into ``django.po`` (if JS strings exist) using ``msgcat``. -3. Renames the result to ``text.po``. +3. Moves the result to ``xblock_/conf/locale/`` at the repository root. The output for each XBlock is a single file at:: - src/xblock_/conf/locale/en/LC_MESSAGES/text.po + xblock_/conf/locale/en/LC_MESSAGES/django.po -Additionally, all per-xblock ``text.po`` files are merged into a single combined file at:: - - src/xblocks_core_locale/conf/locale/en/LC_MESSAGES/django.po - -This combined file is used by the +These per-XBlock files are used by the `openedx-translations `_ pipeline (OEP-58) -to sync translations with Transifex. The per-xblock files are used for local development and testing. +to sync translations with Transifex. Each XBlock is a separate Transifex resource. 3. Create language specific translations ---------------------------------------- @@ -196,7 +191,8 @@ for translation management. Translations are managed centrally through the `openedx-translations `_ repository: 1. A daily GitHub Actions workflow in openedx-translations clones this repo, runs - ``make extract_translations``, and commits the combined ``django.po`` source file. + ``make extract_translations``, and commits each XBlock's ``django.po`` source file under + ``translations/xblocks-core//conf/locale/``. 2. The Transifex GitHub App syncs source strings to the ``openedx-translations`` Transifex project under the ``open-edx`` organization. 3. The Open edX translation community translates strings on Transifex. @@ -206,69 +202,12 @@ Since these XBlocks were extracted from edx-platform, many strings already have in Transifex. The openedx-translations pipeline preserves these so translators do not need to re-translate them. -**Direct Transifex CLI (alternative):** - -Each XBlock also has a ``.tx/config`` for direct Transifex CLI usage. This is useful for -testing or when the openedx-translations pipeline is not available. - -1. Install the Transifex CLI:: - - $ make install_transifex_client - -2. Set your Transifex API token (request access from the Open edX Open Source Team):: - - $ export TX_TOKEN= - -3. Pull or push translations:: - - $ make pull_translations - $ make push_translations - -See `Transifex CLI configuration `_ for more details. - -3.3 Compile translations -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once translations are in place, use the following Make target to compile the translation catalogs ``.po`` into -``.mo`` message files:: - - $ make compile_translations - -This runs ``django-admin compilemessages`` inside each XBlock directory. -See `compilemessages documentation `_. - 4. Use ``gettext`` to translate strings --------------------------------------- -Django will automatically use ``gettext`` and the compiled translations to translate strings. - -Validating and testing translations ------------------------------------ - -**Validate the full translation pipeline** (extract, generate dummy translations, compile, and -check for source drift):: - - $ make validate_translations - -This is the target used in CI (via ``tox -e translations``). It runs the following targets in order: - -**Generate dummy (fake) translations** in the Esperanto (``eo``) and fake-RTL (``rtl``) locales for -visual testing:: - - $ make dummy_translations - -You can trigger the display by setting your browser's language to Esperanto and navigating to a page. -Instead of plain English strings you should see accented English like:: - - The Future of Online Education --> The Futuré of Onliné Education - -**Compile translations** (required after pull or dummy generation):: - - $ make compile_translations - -**Check if source translation files are up-to-date** with the current source code:: - - $ make detect_changed_source_translations +Open edX pulls the translations from openedx-translations with ``atlas`` +(``make pull_xblock_translations`` in openedx-platform), and Django uses ``gettext`` to +translate strings. Make targets reference ---------------------- @@ -280,38 +219,16 @@ Make targets reference * - Target - Description * - ``make extract_translations`` - - Extract translatable strings into ``text.po`` for each XBlock - * - ``make compile_translations`` - - Compile ``.po`` files into ``.mo`` files for each XBlock - * - ``make dummy_translations`` - - Generate dummy Esperanto/RTL ``.po`` files for testing - * - ``make build_dummy_translations`` - - Generate and compile dummy translations - * - ``make validate_translations`` - - Full validation: dummy build + source drift detection (CI target) - * - ``make detect_changed_source_translations`` - - Check if source ``.po`` files are up-to-date - * - ``make pull_translations`` - - Pull translations from Transifex - * - ``make push_translations`` - - Extract and push source translations to Transifex - * - ``make install_transifex_client`` - - Install the Transifex CLI + - Extract translatable strings into ``/conf/locale/`` for each XBlock Troubleshooting ~~~~~~~~~~~~~~~ -If there are any errors compiling ``.po`` files, validate them:: - - $ make validate_translations - -See `django's i18n troubleshooting documentation -`_ -for more information. +If gettext wrongly flags strings containing ``%`` as python-format, see +`Django's i18n troubleshooting documentation +`_. **Common issues:** - ``i18n_tool: command not found`` -- Run ``make requirements`` to install ``edx-i18n-tools``. - ``msgcat: command not found`` -- Install GNU gettext (``brew install gettext`` on macOS). -- Transifex push/pull errors -- Ensure ``TX_TOKEN`` is set and you have access to the ``open-edx`` - organization. Run ``make install_transifex_client`` if the ``tx`` CLI is missing. diff --git a/docs/internationalization.rst b/docs/internationalization.rst index ea8fae5e..25e832f3 100644 --- a/docs/internationalization.rst +++ b/docs/internationalization.rst @@ -14,16 +14,13 @@ Project structure ***************** Each XBlock in this repository manages its own translations independently: -- **Config**: ``src/xblock_/conf/locale/config.yaml`` -- defines supported languages and +- **Config**: ``src/xblock_/conf/locale/config.yaml`` -- defines the source language and ignored directories. -- **Source strings**: ``src/xblock_/conf/locale/en/LC_MESSAGES/text.po`` -- extracted - English strings (Python, HTML, and JavaScript combined into a single file). -- **Transifex mapping**: ``src/xblock_/.tx/config`` -- maps the local ``conf/locale/`` - paths to the Transifex resource for that XBlock. -- **Combined source file**: ``src/xblocks_core_locale/conf/locale/en/LC_MESSAGES/django.po`` -- all - per-xblock ``text.po`` files merged into one, used by the openedx-translations pipeline (OEP-58). +- **Source strings**: ``xblock_/conf/locale/en/LC_MESSAGES/django.po`` (at the repository + root) -- extracted English strings (Python, HTML, and JavaScript combined into a single file), + used by the openedx-translations pipeline (OEP-58). -All ``make`` targets iterate over every XBlock that has a ``conf/`` directory automatically. +``make extract_translations`` iterates over every XBlock that has a ``conf/`` directory automatically. Updating Translations ********************* @@ -37,8 +34,8 @@ the `openedx-translations`_ repository rather than directly via Transifex. 1. A daily GitHub Actions workflow in openedx-translations clones this repo and runs ``make extract_translations``. -2. The combined ``django.po`` file at ``src/xblocks_core_locale/conf/locale/en/`` is committed to - openedx-translations. +2. Each XBlock's ``django.po`` file is committed to openedx-translations under + ``translations/xblocks-core//conf/locale/``. 3. The Transifex GitHub App syncs source strings to the ``openedx-translations`` Transifex project under the ``open-edx`` organization. 4. The Open edX translation community translates strings on `Transifex`_. @@ -49,14 +46,6 @@ in Transifex. The pipeline preserves these so translators do not need to re-tran .. _Transifex: https://www.transifex.com/ -**Direct Transifex CLI (alternative):** - -Each XBlock also has a ``.tx/config`` for direct Transifex CLI usage when the openedx-translations -pipeline is not available. This requires access to the ``open-edx`` Transifex organization. - -1. Install the Transifex CLI: ``make install_transifex_client`` -2. Set your API token: ``export TX_TOKEN=`` - .. list-table:: :widths: 35 65 :header-rows: 1 @@ -64,34 +53,4 @@ pipeline is not available. This requires access to the ``open-edx`` Transifex or * - Target - Description * - ``make extract_translations`` - - Extract translatable strings into ``text.po`` for each XBlock - * - ``make compile_translations`` - - Compile ``.po`` files into ``.mo`` files for each XBlock - * - ``make pull_translations`` - - Pull translations from Transifex for each XBlock - * - ``make push_translations`` - - Extract and push source translations to Transifex for each XBlock - * - ``make validate_translations`` - - Full validation pipeline (dummy build + source drift detection) - * - ``make detect_changed_source_translations`` - - Check if source ``.po`` files are up-to-date with the code - * - ``make dummy_translations`` - - Generate dummy Esperanto/RTL ``.po`` files for testing - * - ``make build_dummy_translations`` - - Generate and compile dummy translations - * - ``make install_transifex_client`` - - Install the Transifex CLI - -Fake Translations -***************** -As you develop features it may be helpful to know which strings have been marked for translation, and which are not. -Use the ``dummy_translations`` make target for this purpose. This target will extract all strings marked for -translation and generate fake translations in the Esperanto (eo) and fake-RTL (rtl) language directories. -Run ``make compile_translations`` afterwards (or use ``make build_dummy_translations`` to do both at once). - -You can trigger the display of the translations by setting your browser's language to Esperanto (eo), and navigating to -a page on the site. Instead of plain English strings, you should see specially-accented English strings that look -like this: - - Thé Fütüré øf Ønlïné Édüçätïøn Ⱡσяєм ι# Før änýøné, änýwhéré, änýtïmé Ⱡσяєм # - + - Extract translatable strings into ``/conf/locale/`` for each XBlock