Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update for OEP-58 implementation - FC-55 and FC-12 #540

Merged
merged 2 commits into from
Sep 23, 2024
Merged

docs: update for OEP-58 implementation - FC-55 and FC-12 #540

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3947c42
docs: update for OEP-58 implementation
OmarIthawi Jul 20, 2024
a1198f3
docs: update enable-translations-new-repo.rst for OEP-58 closure
OmarIthawi Jul 20, 2024
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
85 changes: 41 additions & 44 deletions source/developers/how-tos/enable-translations-new-repo.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,20 +45,18 @@ workflow:
- 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 <https://github.com/openedx/xblock-drag-and-drop-v2/blob/3900a4eba5befbbaea636c5e256aaabcd985e64d/drag_and_drop_v2/drag_and_drop_v2.py#L343-L349>`_. Note: this requires `XBlock 1.9.1`_ or newer, and `edx-platform e7fc0c6`_ or newer.
#. 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 <https://github.com/openedx/xblock-drag-and-drop-v2/blob/3900a4eba5befbbaea636c5e256aaabcd985e64d/drag_and_drop_v2/drag_and_drop_v2.py#L343-L349>`_. Note: this requires `XBlock 1.9.1`_ or newer, and edx-platform Redwood 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
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::

python-translations:
strategy:
matrix:
repo:
...
- repo_name: xblock-drag-and-drop-v2
...
const allPythonRepos = [
...
'xblock-drag-and-drop-v2',
...
]


#. Add the repository to the `transifex.yml`_ file in the `openedx-translations repo`_.
Expand All @@ -72,7 +70,7 @@ workflow:

#. Verify the workflow is syncing the translations properly as described in the :ref:`debugging-translations` section.

#. Install the XBlock or plugin in your local `Tutor`_ or `devstack`_ environment. Run
#. Install the XBlock or plugin in your local `Tutor`_ environment. Run
``make pull_translations`` in the ``edx-platform`` repo to preview the translations.


Expand Down Expand Up @@ -103,16 +101,14 @@ To include a Microservice Python repository in the translations workflow:

#. 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
Add a new entry under the ``setup-matrix`` section. For example for the `credentials`_ repo it should have
the following entry::

django-translations:
strategy:
matrix:
repo:
...
- repo_name: credentials
...
const allPythonRepos = [
...
'credentials',
...
]

#. Create a draft pull request in the `openedx-translations repo`_

Expand Down Expand Up @@ -147,16 +143,14 @@ To include a React repository in the translations workflow:

#. 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
Add a new entry under the ``setup-matrix`` section. For example for the `frontend-app-learning`_ repo
should have the following entry::

js-translations:
strategy:
matrix:
repo:
...
- frontend-app-learning
...
const allJavascriptRepos = [
...
'frontend-app-learning',
...
]

#. Create a draft pull request in the `openedx-translations repo`_

Expand All @@ -183,35 +177,41 @@ 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``.
#. 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``
#. Fork the `openedx-translations repo`_ e.g. ``your-github-user-or-org/openedx-translations``.
#. In your fork, modify the `extract-translation-source-files.yml`_ file in a new branch e.g. ``your-branch-name``.
#. Go to the ``Actions`` tab in your repository (i.e. ``your-github-user-or-org/openedx-translations``)
#. From the left section, pick the `"Extract Translation Source Files" section in your fork`_
#. Click on the "Run workflow" dropdown button with the following parameters:

#. Modify the `extract-translation-source-files.yml`_ workflow to run ``pull_request`` events.
- **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

#. Verify that an automated source translation pull request is created on your fork similar to the
`chore - add updated translation source files`_ pull request.
#. Verify the action ran successfully
#. 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:

#. 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``.
#. 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``

#. 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``.
#. If you're testing an XBlock or an ``edx-platform`` plugin, run the ``make pull_translations`` command in
the ``edx-platform``.

#. 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`_.
This step assumes that you're already familiar with `Tutor`_.


.. _debugging-translations:
Expand Down Expand Up @@ -260,11 +260,10 @@ After adding a repository to the `openedx-translations repo`_ verify the followi
.. _chore - add updated translation source files #615: https://github.com/openedx/openedx-translations/pull/615
.. _Updates for file translations/frontend-app-learning/src/i18n/transifex_input.json in de on branch main #598: https://github.com/openedx/openedx-translations/pull/598
.. _course discovery translations: https://github.com/openedx/openedx-translations/tree/f0315d4/translations/course-discovery/course_discovery/conf/locale
.. _frontend-lib-special-exams testing pull request: https://github.com/Zeit-Labs/openedx-translations/pull/1/files
.. _transifex.yml: https://github.com/openedx/openedx-translations/blob/main/transifex.yml
.. _Drag and Drop XBlock transifex.yml entry: https://github.com/openedx/openedx-translations/blob/19c0fcbbc334c56022df355fa5b529e5853d30f9/transifex.yml#L253-L259
.. _edx-platform e7fc0c6: https://github.com/openedx/edx-platform/commit/e7fc0c6b6f8b44fa4bcc71d00ae2931f91cc664c
.. _XBlock 1.9.1: https://github.com/openedx/XBlock/releases/tag/xblock-1.9.1
.. _"Extract Translation Source Files" section in your fork: https://github.com/Zeit-Labs/openedx-translations/actions/workflows/extract-translation-source-files.yml

.. _edx-platform: https://github.com/openedx/edx-platform
.. _credentials: https://github.com/openedx/credentials
Expand All @@ -273,6 +272,4 @@ After adding a repository to the `openedx-translations repo`_ verify the followi
.. _frontend-app-learning: https://github.com/openedx/frontend-app-learning

.. _Tutor: https://docs.tutor.overhang.io/
.. _devstack: https://github.com/openedx/devstack/
.. _chore - add updated translation source files: https://github.com/Zeit-Labs/openedx-translations/pull/49/commits/e872c962d6873b9f178f8901ef661c7f1c266397
.. _Tutor MFE Docker build: https://github.com/overhangio/tutor-mfe/blob/master/tutormfe/templates/mfe/build/mfe/Dockerfile
33 changes: 20 additions & 13 deletions source/translators/concepts/translation-process.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,11 @@ your running code.

flowchart TD
annotate(Annotate Strings) -->
extract(Extract Strings For Translation) -->
upload(Upload to Transifex) -->
extract(Extract Source Strings for Translation) -->
upload(Upload Source Strings to Transifex) -->
translate(Translate Strings) -->
download(Download for Use)
sync(Sync Translated Strings to openedx-translations) -->
use(Using Translation)

Annotating and Extracting Strings
*********************************
Expand Down Expand Up @@ -51,6 +52,9 @@ strings for translation.
To learn more about how to annotate strings for translation, see the annotation reference
(link tbd).

The `extraction process`_ is managed by the `openedx-translations repository`_
which stores the English source translations in git.

.. Annotation reference issue: https://github.com/openedx/docs.openedx.org/issues/211

.. _django's builtin translation tooling: https://docs.djangoproject.com/en/4.1/topics/i18n/translation/
Expand All @@ -60,25 +64,24 @@ Getting Strings Translated
**************************

The tool we use to translate strings is Transifex. Once translation source strings are
extracted from code to files, the Transifex CLI tool can be used to upload them for
translation. Translation is done by the community and coordinated by the Translations
extracted from code to files, the `GitHub Transifex App`_ will upload the soruce translations
to Transifex so translators can do their work.

Translation is done by the community and coordinated by the Translations
Working Group. For more information see :doc:`../quickstarts/start-translating-openedx`.

Using Translations
******************

In order to use translated strings, they must be downloaded as files. Translation files
are periodically updated in the openedx-translations_ repository.
are automatically synced into the openedx-translations_ repository by the `GitHub Transifex App`_.

The openedx-atlas_ CLI tool was built to help you download translation files for a
specific part of the codebase.
The openedx-atlas_ CLI tool has been built to help you download translation files for a
specific part of the codebase. This process is automated and included in the `Tutor Dockerfile`_.

.. code-block:: bash
During development, it is possible to download the latest files into a repositories source code e.g. ``edx-platform`` or ``frontend-app-learning`` by running the ``make pull_translations`` command in the desired repository's source code.

cd /path/to/credentials
# pull down the latest translations for all available
# languages for the credentials application
atlas pull --directory credentials
The specifics the Makefile program and ``atlas pull`` parameters are described in details in the :doc:`/developers/how-tos/enable-translations-new-repo` document.

Once the translations have been downloaded, you can simply start up the service and the
translations will be available to the user based on their profile settings.
Expand All @@ -87,3 +90,7 @@ translations will be available to the user based on their profile settings.

.. _openedx-translations: https://github.com/openedx/openedx-translations
.. _openedx-atlas: https://github.com/openedx/openedx-atlas
.. _GitHub Transifex App: https://github.com/apps/transifex-integration
.. _openedx-translations repository: https://github.com/openedx/openedx-translations
.. _extraction process: https://github.com/openedx/openedx-translations/actions/workflows/extract-translation-source-files.yml
.. _Tutor Dockerfile: https://docs.tutor.edly.io/configuration.html#getting-and-customizing-translations