-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
d193953
commit 0c496a8
Showing
1 changed file
with
139 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,139 @@ | ||
| Atlas Translations Management Design | ||
| #################################### | ||
|
|
||
| Date: 25 March 2024 | ||
|
|
||
| Status | ||
| ****** | ||
| Pending | ||
|
|
||
| Context | ||
| ******* | ||
|
|
||
| Open edX microservices and micro-frontends is using `OEP-58`_ to pull the latest | ||
| translations from the `openedx-translations repository`_. | ||
|
|
||
| The gist of `OEP-58`_ is two processes: | ||
|
|
||
| - Extract the English translation source entries and commit them into the `openedx-translations repository`_ | ||
| - Provide a command to pull translations in both development and web server image builds | ||
|
|
||
| Microservices, micro-frontends, XBlocks and plugins uses one or two files which makes it easier for Translators | ||
| to locate and translate relevant resources. | ||
|
|
||
| The `edx-platform`_ used to have 7 different resources, but this has been deprecated in favor of ``edx-platform.po`` | ||
| and ``edx-platform-js.po`` files. The details in the `edx-platform resources combination decision`_. | ||
|
|
||
| The ``openedx-app-ios`` uses a clean architecture. Therefore, each app has its own i18n strings files. This is | ||
| useful for Developer Experience, but we believe it's not good for Translator Experience. | ||
|
|
||
| Decision | ||
| ******** | ||
|
|
||
| This decision will require few changes to the translation workflow in comparison with the old ``edx-app-ios``: | ||
|
|
||
| - Translation files are no longer comitted directly in the mobie app ``openedx-app-ios/android`` repositories | ||
| - Keep the i18n string files split into each clean architecture app without hurting Developer Experience. | ||
| - Identical string IDs across the application will be treated as the same string/translation. | ||
| For example, ``BUTTON_CLOSE="Close"`` in dashboard is the same ``BUTTON_CLOSE="CLOSE"`` in profile app despite | ||
| value difference (a new script). | ||
| - String files are combined into a single file before preparing it to Transifex | ||
| (through the `openedx-translations repository`_) | ||
| - Translators can translate the entire app as a single resource | ||
| - Before releasing to App Store, developers need to run a new ``make pull_translations`` command | ||
| - After translations is pulled the translation file is split again into each clean architecture application | ||
| as if it has been individual resource (a new script) | ||
|
|
||
|
|
||
| String files 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 with strings de-duplicated, | ||
| while Engineers need to have clean architecture with strings split into each app to aid maintainability. | ||
|
|
||
| Combining the files during ``combine_translations`` | ||
| --------------------------------------------------- | ||
|
|
||
| Android and iOS apps already extracts the ``.strings`` files therefore there's no need | ||
| for a dedicated ``extract_translations`` step. | ||
|
|
||
| However, combining the string files to aid Translator Experience in the following manner: | ||
|
|
||
| Suppose we have two apps with one string source file in each:: | ||
|
|
||
| Course/Course/en.lproj/Localizable.strings | ||
| Dashboard/Dashboard/en.lproj/Localizable.strings | ||
|
|
||
| This script will collect the strings, remove uneeded comments and combine them in a temporary file:: | ||
|
|
||
| I18N/I18N/en.lproj/Localizable.strings | ||
|
|
||
|
|
||
| This file will be committed into the `openedx-translations repository`_ as described in `OEP-58`_. | ||
|
|
||
| This process happens entirely on the CI server (GitHub in this case) after each pull request merge without developer | ||
| intervention. | ||
|
|
||
| GitHub Actions CI Script to avoid duplicate string IDs | ||
| ------------------------------------------------------ | ||
|
|
||
| A new script will be created to ensure we don't have duplicate IDs with different content. | ||
|
|
||
| For example: | ||
|
|
||
| If the Dashboard has ``BUTTON_CLOSE="Close"`` while Course app has ``BUTTON_CLOSE="CLOSE TAB"``, this | ||
| script should fail and require either making the string to match or the ID to be different. | ||
|
|
||
| Spitting the files after ``pull_translations`` | ||
| ---------------------------------------------- | ||
|
|
||
| After pulling the translations from the `openedx-translations repository`_ via ``atlas pull``, there will be a single | ||
| strings file for each language: | ||
|
|
||
| .. code:: | ||
| I18N/I18N/uk.lproj/Localizable.strings | ||
| I18N/I18N/ar.lproj/Localizable.strings | ||
| I18N/I18N/fr.lproj/Localizable.strings | ||
| I18N/I18N/es-419.lproj/Localizable.strings | ||
| - The string will run through each i18n strings file in the clean architecture. | ||
| - Identify which entries in the app strings file. | ||
| - Create strings file in the each app and put the strings that exists in the : | ||
|
|
||
|
|
||
| .. code:: | ||
| Course/Course/uk.lproj/Localizable.strings | ||
| Course/Course/ar.lproj/Localizable.strings | ||
| Course/Course/fr.lproj/Localizable.strings | ||
| Course/Course/es-419.lproj/Localizable.strings | ||
| ... | ||
| Dashboard/Dashboard/uk.lproj/Localizable.strings | ||
| Dashboard/Dashboard/ar.lproj/Localizable.strings | ||
| Dashboard/Dashboard/fr.lproj/Localizable.strings | ||
| Dashboard/Dashboard/es-419.lproj/Localizable.strings | ||
| This script should ensure that every entry in the source English file, should have an entry in the | ||
| translated files even if it has no translations. This will ensure app builds don't fail. | ||
|
|
||
|
|
||
| Python language for scripting | ||
| ============================= | ||
| Python will be used in scripting the pull/push when needed. | ||
| This is in-line with the Theming tooling which is has been written in Python. | ||
|
|
||
|
|
||
| Alternatives | ||
| ************ | ||
| - Writing scripts in native languages such as Kotlin and Swift has been dismissed as per core team request. | ||
| - Pushing individual app resources into the `openedx-translations repository`_ is dismissed to avoid | ||
| having too many resources per mobile app in the Transifex project. | ||
|
|
||
|
|
||
| .. _OEP-58: https://docs.openedx.org/en/latest/developers/concepts/oep58.html | ||
| .. _openedx-translations repository: https://github.com/openedx/openedx-translations | ||
| .. _edx-platform: https://github.com/openedx/edx-platform | ||
| .. _edx-platform resources combination decision: https://github.com/openedx/edx-platform/blob/master/docs/decisions/0018-standarize-django-po-files.rst |