docs: add the Python Repo section into OEP-58 docs

source/developers/how-tos/enable-translations-new-repo.rst

@@ -1,25 +1,226 @@
-###################################
 Enabling Translations on a New Repo
 ###################################
 
 .. contents::
  :local:
  :depth: 2
-
-===========
-Python Repo
-===========
 
-TODO: How to enable translations infrastructure on a Python 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:
+
+#. 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``
+
+#. 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::
+
+    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
+            ...
+
+#. 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.
+
+#. 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 :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.
+
+
+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`_ 
+- `credentials`_
+- `ecommerce`_
+- `course-discovery`_
+
+
+#. If you are creating a new repository, use the `cookiecutter-django-ida`_
+   template.
+
+**TODO:** How to enable translations infrastructure on a Django microservice
+
+#. Create a draft pull request in the `openedx-translations repo`_
+
+#. 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.
+
+#. 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``.
+
+React Repos
 ===========
-Django Repo
-===========
 
-TODO: How to enable translations infrastructure on a Django repo
+#. If you are creating a new repository, use `frontend-template-application`_.
+
+**TODO:** How to enable translations infrastructure on a React repo
+
+#. 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.
+
+#. 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.
+
+#. 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 :ref:`debugging-translations` section.
+
+#. Depending on how you deploy the micro-frontend, include the ``pull_translations`` make rule with the
+   ``OPENEDX_ATLAS_PULL`` environment variable set to ``true`` e.g
+   ``$ OPENEDX_ATLAS_PULL=true make pull_translations``.
+
+   This command needs to run before ``npm build`` in order to include updated translations in final micro-frontend
+   build.
+
+
+Testing and Debugging
+*********************
+
+.. _testing-in-your-fork:
+
+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 include your
+   repo and your organization name ...... **TODO:** add example https://github.com/Zeit-Labs/openedx-translations/pull/1/files
+
+**TODO:** Add full test instructions like Shadi, Brian and Omar tested in their forks.
+
+#. 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 and Open edX plugin, run the ``$ OPENEDX_ATLAS_PULL=true make pull_translations`` command in
+   the ``edx-platform`` repo. Otherwise, run ``$ OPENEDX_ATLAS_PULL=true 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:
+
+
+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.
+
+
+
+.. _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
+.. _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
+.. _cookiecutter-django-ida: https://github.com/openedx/edx-cookiecutters/tree/master/cookiecutter-django-ida
+.. _openedx-translations project: https://app.transifex.com/open-edx/openedx-translations/dashboard/
+.. _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
 
-==========
-React Repo
-==========
+.. _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
 
-TODO: How to enable translations infrastructure on a React repo
+.. _Tutor: https://docs.tutor.overhang.io/
+.. _devstack: https://github.com/openedx/devstack/