fix: Apply suggestions from code review

Co-authored-by: Brian Smith <[email protected]>

docs/0002-atlas-translations-management.rst

@@ -19,41 +19,65 @@ The main changes that `OEP-58`_ introduced to the Open edX project are the follo
 - The `GitHub Transifex app`_ will automatically commit the translations to the `openedx-translations repository`_
 - Provide a command that utilizes the `atlas`_ tool to pull translations in both development and web server image builds
 
-Microservices, micro-frontends, XBlocks and plugins use as few translation files as possible to makes it easier for Translators
+Microservices, micro-frontends, XBlocks and plugins use as few translation files as possible to make it easier for Translators
 to locate and translate relevant resources.
 
-`edx-platform`_ translations strings used to be split between 7 files, but this has been deprecated in favor of
+`edx-platform`_ translation strings used to be split between 7 files, but this has been deprecated in favor of
 ``edx-platform.po`` and ``edx-platform-js.po`` files.
 More details are available in the `edx-platform resources combination decision document`_.
 
-The `openedx-app-ios`_ uses a clean architecture. Therefore, each clean architecture module has its own i18n
-localizable strings file. This is useful for Developer Experience.
-However, it's not good for Translator Experience because translators
-often are unaware of the application engineering architecture and would like to be able to quickly search for strings
-regardless of their location in the code.
+`openedx-app-ios`_ uses a modular architecture. Each module has its own i18n
+localizable strings file. This is useful for Developer Experience, but can be harmful
+to the Translator Experience. Translators often are unaware of the engineering
+architecture and would like to be able to quickly search for strings regardless of
+their location in the code.
 
 Decision
 ********
 
-This decision requires a few changes to the mobile app translation workflow:
+Combine English ``Localizable.strings`` files from mobile app modules before pushing them to the `openedx-translations repository`_.
+split back the translated files into the modules after pulling from the `openedx-translations repository`_ via
+`atlas`_.
 
-- Translation files are no longer comitted directly to the mobie app repositories (`openedx-app-ios`_ / `openedx-app-android`_)
-- Keep the i18n string files split into each module without hurting Developer Experience.
-- String files are combined into a single file before uploading it to Transifex
-  (through the `openedx-translations repository`_)
-- Translators can translate the entire app within a single transifex resource
-- Before releasing to App Store, developers need to run a new ``make pull_translations`` command
-- After translations are pulled the translation files are split into each module
-  as if it has been individual resource (a new script)
+The `OEP-58`_ workflow for mobile apps will proceed as follows:
+
+* The `openedx-translations repository`_ runs a daily cronjob to collect strings from the `openedx-app-ios`_ ``main`` branch.
+
+  * The `extract-translation-source-files.yml`_ workflow will clone the `openedx-app-ios`_.
+
+  * The `extract-translation-source-files.yml`_ workflow will run the `openedx-app-ios`_'s ``make combine_translations``.
+
+  * The ``make combine_translations`` combines English ``Localizable.strings`` files from the mobile app modules into a single ``I18N/I18N/en.lproj/Localizable.strings`` file.
+
+  * The ``I18N/I18N/en.lproj/Localizable.strings`` is committed in the `openedx-translations repository`_.
+
+  * The `GitHub Transifex app`_ will fetch the updated English source ``.strings`` files from `openedx-translations repository`_
+
+  * Translators can translate the strings in the `Transifex openedx-translations project`_
 
+  * The `GitHub Transifex app`_ syncs the translated strings into the `openedx-translations repository`_
+
+* Developers run ``make pull_translations`` to pull the translations from the `openedx-translations repository`_
+
+  * The ``make pull_translations`` run `atlas pull`_ command pulls the translations
+
+  * The translation will be pulled in a single file for each language e.g. ``I18N/I18N/ar.lproj/Localizable.strings``
+
+  * Then ``make pull_translations`` will run ``python scripts/split_translation_files.py`` script to split the translations into the modules e.g. ``Course/Course/ar.lproj/Localizable.strings``
+
+Notable changes
+===============
+
+- Translation files are no longer committed directly to the mobie app repositories (`openedx-app-ios`_ / `openedx-app-android`_)
+- Before releasing to App Store, developers need to run a new ``make pull_translations`` command
 
 String file combination and splitting process
 =============================================
 This is a new process that's being introduced to have the best combination
 of Developer Experience and Translator Experience.
 
-Translators need to have less resources as possible,
-while Engineers need to have clean architecture with strings split into each app to aid maintainability.
+The best experience for Translators requires combining source strings into as few transifex resources as possible.
+The best experience for Engineers requires splitting translation source files to fit within the modular architecture.
 
 Combining the files during ``combine_translations``
 ---------------------------------------------------
@@ -160,3 +184,5 @@ Alternatives
 .. _GitHub Transifex app: https://github.com/apps/transifex-integration
 .. _openedx-app-android: https://github.com/openedx/openedx-app-android
 .. _openedx-app-ios: https://github.com/openedx/openedx-app-ios
+.. _extract-translation-source-files.yml: https://github.com/openedx/openedx-translations/blob/2566e0c9a30d033e5dd8d05d4c12601c8e37b4ef/.github/workflows/extract-translation-source-files.yml
+.. _Transifex openedx-translations project: https://app.transifex.com/open-edx/openedx-translations/content/