Skip to content
Draft
Show file tree
Hide file tree
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
113 changes: 15 additions & 98 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://docs.openedx.org/projects/xblock/en/latest/xblock-tutorial/edx_platform/edx_lms.html#internationalization-support>`_.

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_<name>/conf/locale/`` and its own Transifex resource mapping under
``src/xblock_<name>/.tx/config``. All Make targets iterate over every XBlock automatically.
``src/xblock_<name>/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:

Expand Down Expand Up @@ -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_<name>/conf/locale/`` at the repository root.

The output for each XBlock is a single file at::

src/xblock_<name>/conf/locale/en/LC_MESSAGES/text.po
xblock_<name>/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 <https://github.com/openedx/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
----------------------------------------
Expand Down Expand Up @@ -196,7 +191,8 @@ for translation management. Translations are managed centrally through the
`openedx-translations <https://github.com/openedx/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/<module_name>/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.
Expand All @@ -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=<your-api-token>

3. Pull or push translations::

$ make pull_translations
$ make push_translations

See `Transifex CLI configuration <https://developers.transifex.com/docs/cli>`_ 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 <https://docs.djangoproject.com/en/5.2/topics/i18n/translation/#compiling-message-files>`_.

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
----------------------
Expand All @@ -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 ``<module_name>/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
<https://docs.djangoproject.com/en/5.2/topics/i18n/translation/#troubleshooting-gettext-incorrectly-detects-python-format-in-strings-with-percent-signs>`_
for more information.
If gettext wrongly flags strings containing ``%`` as python-format, see
`Django's i18n troubleshooting documentation
<https://docs.djangoproject.com/en/5.2/topics/i18n/translation/#troubleshooting-gettext-incorrectly-detects-python-format-in-strings-with-percent-signs>`_.

**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.
57 changes: 8 additions & 49 deletions docs/internationalization.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,13 @@ Project structure
*****************
Each XBlock in this repository manages its own translations independently:

- **Config**: ``src/xblock_<name>/conf/locale/config.yaml`` -- defines supported languages and
- **Config**: ``src/xblock_<name>/conf/locale/config.yaml`` -- defines the source language and
ignored directories.
- **Source strings**: ``src/xblock_<name>/conf/locale/en/LC_MESSAGES/text.po`` -- extracted
English strings (Python, HTML, and JavaScript combined into a single file).
- **Transifex mapping**: ``src/xblock_<name>/.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_<name>/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
*********************
Expand All @@ -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/<module_name>/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`_.
Expand All @@ -49,49 +46,11 @@ 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=<your-api-token>``

.. list-table::
:widths: 35 65
:header-rows: 1

* - 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 ``<module_name>/conf/locale/`` for each XBlock
Loading