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

See also

OEP-58 Overview

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:

  1. 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.

  2. 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

  3. 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 Redwood or newer.

  4. Add the repository to extract-translation-source-files.yml in the openedx-translations repo.

    Add a new entry under the setup-matrix section. For example, the XBlock located at https://github.com/openedx/xblock-drag-and-drop-v2 should have the following entry:

    const allPythonRepos = [
    ...
    'xblock-drag-and-drop-v2',
    ...
]

  5. 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.

  6. Create a draft pull request in the openedx-translations repo

  7. Follow the instructions in the Testing translations sync in your fork section to verify new repository configuration.

  8. Mark your pull request as ready for review and wait for it to be merged.

  9. Verify the workflow is syncing the translations properly as described in the Debugging translations workflows section.

  10. Install the XBlock or plugin in your local Tutor 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:

  1. 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.

  2. Run make extract_translations. Verify it extracts both django.po and djangojs.po files into the conf/locale directory.

  3. Add the repository to extract-translation-source-files.yml in the openedx-translations repo.

    Add a new entry under the setup-matrix section. For example for the credentials repo it should have the following entry:

    const allPythonRepos = [
    ...
    'credentials',
    ...
]

  4. Create a draft pull request in the openedx-translations repo

  5. Follow the instructions in the Testing translations sync in your fork section to verify the new repository configuration.

  6. Mark your pull request as ready for review and wait for it to be merged.

  7. Verify the workflow is syncing the translations properly as described in the Debugging translations workflows section.

  8. 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:

  1. 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.

  2. 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.

  3. Add the repository to extract-translation-source-files.yml in the openedx-translations repo.

    Add a new entry under the setup-matrix section. For example for the frontend-app-learning repo should have the following entry:

    const allJavascriptRepos = [
    ...
    'frontend-app-learning',
    ...
]

  4. Create a draft pull request in the openedx-translations repo

  5. Follow the instructions in the Testing translations sync in your fork section to verify the new repository configuration.

  6. Mark your pull request as ready for review and wait for it to be merged.

  7. 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:

  1. Add the make extract_translation into your fork of the new repository e.g. your-github-user-or-org/credentials in a new branch e.g. your-branch-name

  2. Fork the openedx-translations repo e.g. your-github-user-or-org/openedx-translations.

  3. In your fork, modify the extract-translation-source-files.yml file in a new branch e.g. your-branch-name.

  4. Go to the Actions tab in your repository (i.e. your-github-user-or-org/openedx-translations)

  5. From the left section, pick the “Extract Translation Source Files” section in your fork

  6. Click on the “Run workflow” dropdown button with the following parameters:

    • Use workflow from your branch: your-branch-name

    • Repository to extract translation source files from: credentials

    • The ref to extract translation source files from: omar/add-pull-translations

    • Click on the “Run workflow” button

  7. Verify the action ran successfully

  8. Verify the new automated branch e.g. automated/extract-translation-source-files-20230903T001829 has been created with a new commit e.g. chore: add updated translation source files has been created

Once all the above steps are verified, the extraction step is ready for use and the pull request has been tested.

In order to test the make pull_translations step, please follow the steps below:

  1. 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.

  2. Temporarily pull translations from the fork using the Makefile command e.g. make ATLAS_OPTIONS="--repository=your-github-user-or-org/openedx-translations --revision=your-branch-name" pull_translations

  3. If you’re testing an XBlock or an edx-platform plugin, run the make pull_translations command in the edx-platform.

  4. 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.

Debugging translations workflows#

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

  1. 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.

  2. Verify that the openedx-translations project has a new resource for the repo.

  3. 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.

  4. 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.

  5. 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.

  6. Verify that the translations can be pulled in the repo as described in the sections above depending on the repo type.

Maintenance chart

Review Date

Working Group Reviewer

Release

Test situation
Contents