From 0db8699b919771b7ff769b4b78a5451b4d13061f Mon Sep 17 00:00:00 2001 From: Omar Al-Ithawi Date: Sat, 4 Nov 2023 19:31:30 +0300 Subject: [PATCH] docs: rejected proposal the fuzzy strings --- docs/decisions/0002-mark-fuzzy-entries.rst | 116 +++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/decisions/0002-mark-fuzzy-entries.rst diff --git a/docs/decisions/0002-mark-fuzzy-entries.rst b/docs/decisions/0002-mark-fuzzy-entries.rst new file mode 100644 index 00000000000..74f5f90eca7 --- /dev/null +++ b/docs/decisions/0002-mark-fuzzy-entries.rst @@ -0,0 +1,116 @@ +Mark invalid entries in po files as fuzzy +######################################### + +Status +****** + +Rejected. + +Context +******* +As of the `OEP-58`_, the Transifex GitHub App is used to sync Translations. +These translations are validated by `LexiQA`_, built-in Transifex quality +checks, and human reviewers. During this synchronization process, the +`Transifex GitHub App`_ creates pull requests to this repository. The +translations in the pull requests are then validated by ``msgfmt`` in CI. + +Problem +******* +There are times when the translations being synchronized fail ``msgfmt`` +validation. This prevents the pull requests from being merged. + + +Default Workflow: Keep pull requests open +******************************************** + +By default pull requests will be kept open and the translators will +need to fix the invalid entries and the `Transifex GitHub App`_ will +update the pull request with the new changes and merge it automatically +if there are no more errors. + +To improve the Translators experience, a notification will be sent to +for invalid entries. An issue has been created to track this work: +`Notify translators about invalid entries`_. + +Rejected Alternative: Mark invalid entries as fuzzy +*************************************************** + +Rejection Reason +================ + +This design decision was rejected because there were multiple issues that +had no feasible solution within the original scope of the `OEP-58`_ +proposal. These issues are listed below: + +- The workflow script edits the translations and effectively hide the + errors, which can be confusing for the translators. Therefore, + a good notification should be + sent to translators to avoid silencing errors. +- Writing to the pull request will not trigger the GitHub Actions workflow, + therefore the pull request cannot be merged unless the commit status + is overridden manually via `GitHub "create a commit status" API`_. +- The solution is ``.po`` file specific. And there's no similar solution for + ``.json``, ``.yaml``, iOS, Android or other translations files. + +Please refer to the original pull request which contains the rejected +implementation: `mark invalid entries as fuzzy | FC-0012`_. + + +Proposed Design +=============== + +A GitHub Actions workflow will be implemented to mark invalid entries in +synchronized ``.po`` files as ``fuzzy``. This will update pull requests +created by the `Transifex GitHub App`_. + +To ensure a safe and reliable workflow, the following workflows will be +combined into one single workflow with multiple jobs: + +#. Run ``python-tests.yml`` to validate the python code +#. Then, run ``validate-translation-files.yml`` which performs the following: + + #. Validate the po-files using ``msgfmt`` + #. Notify the translators about the invalid entries via the preferred + communication channel (Slack, Transifex, GitHub) + #. Edit the po files to mark invalid entries as ``fuzzy``, so it's + excluded from ``.mo`` files + #. Revalidate the files + +#. Commit the updated entries and push to the PR branch +#. Automatically merge the PR + + +Informing the Translators +========================= +Translators can be notified about invalid translations via Slack, Transifex +or GitHub issues depending on the community's preference. + +Pros and Cons +============= + +**Pros** + +* New valid strings would make it into the ``.mo`` files +* There's no need for manual intervention, therefore it's fast and won't + create a backlog of pull requests. +* Rejected strings are easily identifiable by looking in the code, so it's + easy to fix them. +* Translators can be notified about invalid translations via Slack, Transifex, + GitHub depending on the community's preference. + + +**Cons** + +* The workflow script runs and edits the pull request, which can be + confusing for the reviewers. +* Previously valid entries are going to be overwritten with new ``fuzzy`` + strings which will make those entries to be shown in source language + (English). + + +.. _OEP-58: https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0058-arch-translations-management.html +.. _LexiQA: https://help.transifex.com/en/articles/6219179-lexiqa +.. _Transifex GitHub App: https://github.com/apps/transifex-integration +.. _GitHub "create a commit status" API: https://docs.github.com/en/rest/commits/statuses?apiVersion=2022-11-28#create-a-commit-status +.. _mark invalid entries as fuzzy | FC-0012: https://github.com/openedx/openedx-translations/pull/1944 +.. _Notify translators about invalid entries: https://github.com/openedx/openedx-translations/issues/2130