fixup! fix: address bryan's review

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

@@ -52,23 +52,22 @@ Python Django Plugins and XBlocks
 To include a non-microservice Python repository (such as XBlock, Open edX plugin, or library) in the translations
 workflow:
 
-1. If you are creating a new repository, use the: `edx-cookiecutters`_ templates 
-    such as ``django-app`` or ``xblock``.
+#. If you are creating a new repository, use the: `edx-cookiecutters`_ templates such as ``django-app`` or ``xblock``.
 
-2. For existing repos which don't have the ``make extract_translations`` command, it can be copied from the
+#. 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.
 
-3. Run ``make extract_translations``. Verify it extracts files to the ``my_xblock_module/conf/locale``
+#. 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``
 
-4. Add the repository to `extract-translation-source-files.yml`_ in the `openedx-translations repo`_.
+#. 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 
@@ -94,11 +93,15 @@ workflow:
             - repo_name: credentials-themes
             ...
 
-5. Create a pull request in the `openedx-translations repo`_
+#. Create a draft pull request in the `openedx-translations repo`_
 
-6. Verify the workflow is syncing the translations properly as described in the :ref:`debugging-translations` section.
+#. Follow the instructions in the :ref:`testing-in-your-fork` section to verify new repository configuration.
 
-7. Install the XBlock or plugin in your local `Tutor`_ or `devstack`_ environment. Run
+#. 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.
 
 ================================
@@ -112,41 +115,84 @@ edX project. There are many Django microservices in the Open edX ecosystem, such
 - `ecommerce`_
 - `course-discovery`_
 
-1. 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
+**TODO:** How to enable translations infrastructure on a Django microservice
 
-5. Create a pull request in the `openedx-translations repo`_
+#. Create a draft pull request in the `openedx-translations repo`_
 
-6. Verify the workflow is syncing the translations properly as described in the :ref:`debugging-translations` section.
+#. Follow the instructions in the :ref:`testing-in-your-fork` section to verify new repository configuration.
 
-7. Run ``OPENEDX_ATLAS_PULL=true make pull_translations`` to verify translations are pulled from the
+#. 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
 ===========
 
-1. If you are creating a new repository, use `frontend-template-application`_.
+#. If you are creating a new repository, use `frontend-template-application`_.
 
-TODO: How to enable translations infrastructure on a React repo
+**TODO:** How to enable translations infrastructure on a React repo
 
-4. Run ``make extract_translations``. Verify that it creates``src/i18n/transifex_input.json``. This file should be
+#. 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.
 
-5. Create a pull request in the `openedx-translations repo`_
+#. 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.
 
-6. Verify the workflow is syncing the translations properly as described in the :ref:`debugging-translations` section.
+#. Mark your pull request as ready for review and wait for it to be merged.
 
-7. Depending on how you deploy the micro-frontend, include the ``pull_translations`` make rule with the
+#. 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-in-your-fork:
+
+======================================
+Testing translations sync in your fork
+======================================
+
+Before submitting a pull request for review in the `openedx-translations repo`_, it's possible to test the workflow
+in your fork by following the steps below:
+
+#. Fork the `openedx-translations repo`_.
+#. Make a pull request in your fork and modify the `extract-translation-source-files.yml`_ workflow to include your
+   repo and your organization name ...... **TODO:** add example
+
+**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 on the upstream `openedx-translations repo`_ yet.
+
+   We recommend copying an existing translations. For example to test `credentials`_ we would copy the
+   `course discovery translations`_ and modifying it to include `credentials`_ conf/locale.
+
+#. Temporarily edit the ``Makefile`` so the ``pull_translations`` step pulls via 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.
+
+   This step assumes that you're already familiar with `Tutor`_ and/or `devstack`_.
+
+
 .. _debugging-translations:
 
 ================================
@@ -155,31 +201,29 @@ Debugging translations workflows
 
 After adding a repository to the `openedx-translations repo`_ verify the following in the next day:
 
-1. The `extract-translation-source-files.yml`_ GitHub workflow worked successfully and the build passes in the
+#. 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.
+#. 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
+#. 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 to kick in. The sync is managed by Transifex and usually it kicks in less than an hour
+#. Wait for the next sync to kick in. The sync is managed by Transifex and usually it kicks in less than an hour
    which we'll verify in the next step. The `Transifex GitHub App sync logs`_ shows the most recent sync results.
 
-5. Verify that the Transifex GitHub App created sync pull requests and auto-merged it to the repo.
+#. 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
+#. 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
@@ -194,7 +238,7 @@ 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
 
 .. _edx-platform: https://github.com/openedx/edx-platform
 .. _credentials: https://github.com/openedx/credentials