Enabling Translations on a New Repo

Enabling Translations on a New Repo#

Quickstart #

To enable translations on a new repository according to the OEP-58 - Translations Management proposal

Start from an up-to-date cookiecutter (frontend-template-application for Micro-frontends, edx-cookiecutters for Python)
Configure the repository according to the appropriate section later in this document.

Configuration #

Python Django Plugins and XBlocks #

To include a non-microservice Python repository (such as an XBlock, Open edX plugin, or library) in the translations workflow:

Ensure your repository’s Makefile has extract_translations.

If you are creating a new repository, use the edx-cookiecutters templates such as django-app or xblock.

For existing repos which don’t have the make extract_translations command, it can be copied from the edx-cookiecutters Makefile in the corresponding template e.g. cookiecutter-xblock Makefile for XBlocks.

Note

Some repositories use django-manage makemessages. The recommendation is to use i18n_tool extract because it provides more options and cleans .po files.
Run make extract_translations. Verify it extracts files to the my_xblock_module/conf/locale directory. The .po filenames will vary depending on the use case:
- XBlocks: text.po
- Django plugins: django.po
- If the repo uses gettext and has a static directory with JavaScript, it may include djangojs.po
If you need JavaScript translations in your XBlock, use XBlockI18NService.get_javascript_i18n_catalog_url. You can find an example of this in _get_statici18n_js_url in xblock-drag-and-drop-v2/ here. Note: this requires XBlock 1.9.1 or newer, and edx-platform e7fc0c6 or newer.
Add the repository to extract-translation-source-files.yml in the openedx-translations repo.

Add a new entry under the python-translations section. For example, the XBlock located at https://github.com/openedx/xblock-drag-and-drop-v2 should have the following entry:
```
python-translations:
  strategy:
    matrix:
      repo:
        ...
        - repo_name: xblock-drag-and-drop-v2
        ...
```
Add the repository to the transifex.yml file in the openedx-translations repo. Copy the Drag and Drop XBlock transifex.yml entry and modify it to match the new repository.
Create a draft pull request in the openedx-translations repo
Follow the instructions in the Testing translations sync in your fork section to verify new repository configuration.
Mark your pull request as ready for review and wait for it to be merged.
Verify the workflow is syncing the translations properly as described in the Debugging translations workflows section.
Install the XBlock or plugin in your local Tutor or devstack environment. Run make pull_translations in the edx-platform repo to preview the translations.

Django Microservice Repos (IDAs)#

The terms “Microservice” and “Independently Deployable Application (IDA)” are used interchangeably throughout the Open edX project. There are many Django microservices in the Open edX ecosystem, such as:

To include a Microservice Python repository in the translations workflow:

Ensure your repository’s Makefile has extract_translations and pull_translations.

If you are creating a new repository, use the cookiecutter-django-ida template.

For existing repos which don’t have the make extract_translations or make pull_translations command, they can be copied from the edx-cookiecutters Makefile in the cookiecutter-django-ida Makefile for Microservices.
Run make extract_translations. Verify it extracts both django.po and djangojs.po files into the conf/locale directory.
Add the repository to extract-translation-source-files.yml in the openedx-translations repo.

Add a new entry under the python-translations section. For example for the credentials repo it should have the following entry:
```
django-translations:
  strategy:
    matrix:
      repo:
        ...
        - repo_name: credentials
        ...
```
Create a draft pull request in the openedx-translations repo
Follow the instructions in the Testing translations sync in your fork section to verify the new repository configuration.
Mark your pull request as ready for review and wait for it to be merged.
Verify the workflow is syncing the translations properly as described in the Debugging translations workflows section.
Run make pull_translations to verify translations are pulled from the openedx-translations repo into the conf/locale directory. To generate JavaScript translation files you will likely also need to run make static/make static.dev.

React Repos #

To include a React repository in the translations workflow:

Ensure your repository’s Makefile has extract_translations and pull_translations.

If you are creating a new repository, use frontend-template-application.

For existing repos which don’t have the make extract_translations or make pull_translations command, they can be copied from the frontend-template-application Makefile.

The make pull_translations command should accept a ATLAS_OPTIONS environment variable. This is used to pass options to the atlas pull command during build processes like Tutor MFE Docker build.
Run make extract_translations. Verify that it creates src/i18n/transifex_input.json. This file should be excluded from the repo via the .gitignore file.
Add the repository to extract-translation-source-files.yml in the openedx-translations repo.

Add a new entry under the javascript-translations section. For example for the frontend-app-learning repo should have the following entry:
```
js-translations:
  strategy:
    matrix:
      repo:
        ...
        - frontend-app-learning
        ...
```
Create a draft pull request in the openedx-translations repo
Follow the instructions in the Testing translations sync in your fork section to verify the new repository configuration.
Mark your pull request as ready for review and wait for it to be merged.
Verify the workflow is syncing the translations properly as described in the Debugging translations workflows section.

Note

While deploying or building the micro-frontend, ensure make pull_translations is ran before npm build in order to include updated translations in final micro-frontend build.

Testing and Debugging #

Testing translations sync in your fork #

Before submitting a pull request for review in the openedx-translations repo, you should test the workflow on a fork by following the steps below:

Fork the openedx-translations repo.
Make a pull request to your fork and modify the extract-translation-source-files.yml workflow to use your repo, your organization name and the branch in the clone section. For example, the frontend-lib-special-exams testing pull request uses the Zeit-Labs/frontend-lib-special-exams repository with the branch set via ref: fix-i18n.
Modify the extract-translation-source-files.yml workflow to run pull_request events.
Verify that an automated source translation pull request is created on your fork similar to the chore - add updated translation source files pull request.
Add any test translations to your fork of the openedx-translations repo in the repo directory to overcome the fact that translations don’t exist in the upstream openedx-translations repo yet.

We recommend copying existing translations. For example to test credentials we would copy the course discovery translations directory and modify it to include credentials conf/locale.
Temporarily edit the Makefile so the pull_translations step pulls from your fork e.g. atlas pull --repository=Zeit-Labs/openedx-translations.
If you’re testing an Open edX plugin, run the make pull_translations command in the edx-platform repo. Otherwise, run make pull_translations in the repository you’re testing e.g. frontend-app-learning.
Run the application (or plugin) and verify the translations you’ve added are working properly.

Note

This step assumes that you’re already familiar with Tutor and/or devstack.

Debugging translations workflows #

After adding a repository to the openedx-translations repo verify the following the next day:

The extract-translation-source-files.yml GitHub workflow worked successfully and the build passes in the openedx-translations GitHub Actions tab. If something fails, ask for help in the #wg-translations Open edX Slack channel. An example of a successfully generated and merged pull request by the workflow’s edx-transifex-bot is the chore - add updated translation source files #615 pull request.
Verify that the openedx-translations project has a new resource for the repo.
Ensure the new Transifex resource is 100% translated. Alternatively, Open edX Transifex admins can force sync via the “Manual Sync” button in the Transifex GitHub App sync logs page.
Wait for the next sync. The sync is managed by Transifex and usually takes less than an hour (which we’ll verify in the next step). The Transifex GitHub App sync logs show the most recent sync results.
Verify that the Transifex GitHub App created sync pull requests and auto-merged it to the repo. An example of a successfully merged pull request is the Updates for file translations/frontend-app-learning/src/i18n/transifex_input.json in de on branch main #598 pull request.
Verify that the translations can be pulled in the repo as described in the sections above depending on the repo type.

Feedback

Enabling Translations on a New Repo

Contents

Enabling Translations on a New Repo#