Merge pull request #386 from Zeit-Labs/oep58-docs

docs: complete enable-translations-new-repo.rst MFE and microservice sections
openedx · Oct 4, 2023 · a4ce9a2 · a4ce9a2
2 parents 7ead5b8 + 8abe8d8
commit a4ce9a2
Showing 1 changed file with 75 additions and 29 deletions.
diff --git a/source/developers/how-tos/enable-translations-new-repo.rst b/source/developers/how-tos/enable-translations-new-repo.rst
@@ -14,6 +14,8 @@ To enable translations on a new repository according to the `OEP-58 - Translatio
   for Python)
 - Configure the repository according to the appropriate section later in this document.
 
+.. seealso::
+  :doc:`/developers/concepts/oep58`
 
 Configuration
 *************
@@ -24,9 +26,11 @@ 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:
 
-#. If you are creating a new repository, use the `edx-cookiecutters`_ templates such as ``django-app`` or ``xblock``.
+#. Ensure your repository's Makefile has ``extract_translations``.
 
-#. For existing repos which don't have the ``make extract_translations`` command, it can be copied from the
+   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::
@@ -43,29 +47,20 @@ 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 XBlock located in
-   ``https://github.com/openedx/xblock-drag-and-drop-v2`` and has the XBlock Python 
-   module name ``drag_and_drop_v2`` it should have the following entry::
+   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
-              python_module_name: drag_and_drop_v2
             ...
 
-   When adding a theme or any other module that's not an Open edX plugin or an XBlock the entry should
-   added without ``python_module_name`` as demonstrated below::
 
-    python-translations:
-      strategy:
-        matrix:
-          repo:
-            ...
-            - repo_name: credentials-themes
-            ...
+#. 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`_
 
@@ -76,24 +71,46 @@ 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
-   ``OPENEDX_ATLAS_PULL=true make pull_translations`` in the edx-platform repo to preview the translations.
+   ``OPENEDX_ATLAS_PULL=true 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
-- `edx-platform`_ 
+edX project. There are many Django microservices in the Open edX ecosystem, such as:
+
+- `edx-platform`_
 - `credentials`_
 - `ecommerce`_
 - `course-discovery`_
 
+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`_
+   If you are creating a new repository, use the `cookiecutter-django-ida`_
    template.
 
-**TODO:** How to enable translations infrastructure on a Django microservice
+   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`_
 
@@ -104,22 +121,41 @@ edX project. There are many Django microservices in the Open edX ecosystem, such
 #. Verify the workflow is syncing the translations properly as described in the :ref:`debugging-translations` section.
 
 #. Run ``OPENEDX_ATLAS_PULL=true 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``.
+   `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
 ===========
 
-#. If you are creating a new repository, use `frontend-template-application`_.
+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`_.
 
-**TODO:** How to enable translations infrastructure on a React repo
+   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`_.
 
 #. 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 ref:`testing-in-your-fork` section to verify new repository configuration.
+#. Follow the instructions in the :ref:`testing-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.
 
@@ -145,10 +181,15 @@ Before submitting a pull request for review in the `openedx-translations repo`_,
 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 include your
-   repo and your organization name ...... **TODO:** add example https://github.com/Zeit-Labs/openedx-translations/pull/1/files
+#. 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``.
 
-**TODO:** Add full test instructions like Shadi, Brian and Omar tested in their forks.
+#. 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.
@@ -204,6 +245,7 @@ After adding a repository to the `openedx-translations repo`_ verify the followi
 .. _openedx-translations repo:  https://github.com/openedx/openedx-translations
 .. _edx-cookiecutters:  https://github.com/openedx/edx-cookiecutters
 .. _frontend-template-application: https://github.com/openedx/frontend-template-application
+.. _frontend-template-application Makefile: https://github.com/openedx/frontend-template-application/blob/master/Makefile
 .. _OEP-58 - Translations Management: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0058-arch-translations-management.html
 .. _extract-translation-source-files.yml: https://github.com/openedx/openedx-translations/blob/2566e0c9a30d033e5dd8d05d4c12601c8e37b4ef/.github/workflows/extract-translation-source-files.yml#L36-L43
 .. _Transifex GitHub App sync logs: https://github.apps.transifex.com/projects/o:open-edx:p:openedx-translations/openedx/openedx-translations
@@ -212,15 +254,19 @@ After adding a repository to the `openedx-translations repo`_ verify the followi
 .. _openedx-translations GitHub Actions tab: https://github.com/openedx/openedx-translations/actions
 .. _#wg-translations: https://openedx.slack.com/archives/C037XDB9KN1
 
-
 .. _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: https://github.com/openedx/edx-platform
 .. _credentials: https://github.com/openedx/credentials
 .. _ecommerce: https://github.com/openedx/ecommerce
 .. _course-discovery: https://github.com/openedx/course-discovery
+.. _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