From 59ddee7ad3363bf9f4bfae355fa3f24a1bbdfb37 Mon Sep 17 00:00:00 2001 From: Omar Al-Ithawi Date: Sun, 13 Aug 2023 19:45:01 +0300 Subject: [PATCH] docs: decision to standardize django/djangojs po files This contribution is part of the [FC-0012 project](https://openedx.atlassian.net/l/cp/XGS0iCcQ) which is sparked by the [Translation Infrastructure update OEP-58](https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0058-arch-translations-management.html#specification). --- .../0018-standarize-django-po-files.rst | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/decisions/0018-standarize-django-po-files.rst diff --git a/docs/decisions/0018-standarize-django-po-files.rst b/docs/decisions/0018-standarize-django-po-files.rst new file mode 100644 index 000000000000..4020b7c493e9 --- /dev/null +++ b/docs/decisions/0018-standarize-django-po-files.rst @@ -0,0 +1,155 @@ +Standardize ``django.po`` and ``djangojs.po`` files +=================================================== + +Status +------ + +Accepted + +Context +------- + +- The edx-platform splits its translations into ``mako-studio.po``, + ``django-partial.po``, and 9 other files. This was done with the + intention of supporting more languages in the LMS than in + the CMS (Studio). + +- The edx-platform uses the ``i18n_tools segment`` to split the ``django.po`` + and ``djangojs.po`` files into smaller files. This is done with the goal of + making it easier for translators to translate the files. + +- When pulling from Transifex or cutting a new release, the translations are + bundled into 2 files (``django.po`` and ``djangojs.po``). + +- The `FC-0012 project `_ + which implements `Translation Infrastructure update OEP-58`_ + is in progress. Upon completion, all translation files will live in + the new `openedx-translations Transifex project`_. + +- Consequently, repositories like ``edx-platform`` will pull translations via + `openedx-atlas`_ command line tool as described in the `OEP-58`_ proposal. + +- Several special steps would be needed to for the + `extract-translation-source-files.yml`_ GitHub workflow in + the `openedx-translations GitHub repository`_ + to extract the files from the ``edx-platform`` repo. + This seems redundant and and it should be possible to simplify the process. + +Decision: Only use two files for edx-platform translations (``django.po`` and ``djangojs.po``) +---------------------------------------------------------------------------------------------- + +edX Platform will push only two files (``django.po`` and +``djangojs.``) to the `openedx-translations Transifex project`_. + +Consequences +------------ + +Pros: + +- Translators will need to locate only two resources for the ``edx-platform`` + repo as opposed to 11 resources. +- Simplify the ``edx-platform`` translation extraction scripts in the + `extract-translation-source-files.yml`_ GitHub workflow. +- The release cut process will be simplified as well by removing the + translation merger step altogether. +- Translators will need one workflow for both latest (master) and named + releases for the ``edx-platform`` repo. +- Simplifies the work of both the Build Test Release and Transifex working groups. + +Cons: + +- It will be harder for translators to focus on learner-facing text and de-prioritize + educator-facing text. + + +Rejected Alternatives +--------------------- + +Combine into four files +^^^^^^^^^^^^^^^^^^^^^^^ + +This option tries to keep the original idea of splitting to allow translators +to focus on learner-facing text and de-prioritize educator-facing text. + +The four files will be ``platform.po``, ``platform-js.po``, ``studio.po`` +and ``studio-js.po``. + +It will not concern the translators with the technical split +of the files into: ``wiki.po``, ``mako.po``, and ``django-partial.po``, etc. + + +In this option we'll create two new configuration files +``config.extract-oep58.yaml`` and ``config.pull-oep58.yaml`` to combine the +pofiles into the four files and then combine them into two files respectively: + +.. code:: yaml + + # config.extract-oep58.yaml + # This file is used by the ``make extract_translations`` when + # the OPENEDX_COMBINE_FILES environment variable is enabled. + generate_merge: + platform.po: + - django-partial.po + - mako.po + - wiki.po + - edx_proctoring_proctortrack.po + platform-js.po: + - djangojs-partial.po + - djangojs-account-settings-view.po + - underscore.po + studio.po: + - django-studio.po + - mako-studio.po + studio-js.po: + - djangojs-studio.po + - underscore-studio.po + +A corresponding ``Makefile`` change is needed: + +.. code:: make + + extract_translations: ## extract localizable strings from sources + i18n_tool extract -v + if [ -z "$$OPENEDX_COMBINE_FILES" ]; then \ + i18n_tool generate --config=config.extract-oep58.yaml --verbose 1; + fi + +The other file would be ran after ``make pull_translations`` which will +be used to make the final ``django.po`` and ``djangojs.po`` files that are +usable by Django: + +.. code:: yaml + + # config.pull-oep58.yaml + # This file is used by the ``make pull_translations`` when + # the OPENEDX_ATLAS_PULL environment variable is enabled. + generate_merge: + django.po: + - platform.po + - studio.po + djangojs.po: + - platform-js.po + - studio-js.po + + + pull_translations: ## extract localizable strings from sources + if [ -z "$$OPENEDX_ATLAS_PULL" ]; then \ + atlas pull translations/edx-platform/conf/locale + i18n_tool --config=config.pull-oep58.yaml generate --verbose 1; + fi + + +This option involves multiple merge and split steps which adds complexity +for developers. Based on the `feedback in the decision pull request`_, +splitting the resources was a lesser used feature in the Open edX community. +Therefore, this option is rejected because the added complexity of this +option isn't justified. + + +.. _extract-translation-source-files.yml: https://github.com/openedx/openedx-translations/blob/2566e0c9a30d033e5dd8d05d4c12601c8e37b4ef/.github/workflows/extract-translation-source-files.yml +.. _openedx-translations GitHub repository: https://github.com/openedx/openedx-translations +.. _openedx-translations Transifex project: https://app.transifex.com/open-edx/openedx-translations/ +.. _OEP-58: https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0058-arch-translations-management.html#specification +.. _openedx-atlas: https://github.com/openedx/openedx-atlas/ +.. _Translation Infrastructure update OEP-58: https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0058-arch-translations-management.html#specification +.. _feedback in the decision pull request: https://github.com/openedx/edx-platform/pull/32994#issuecomment-1677390405