This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 8de37c3b152 Update i18n policy and related instructions for Release
Managers (2025-09-13) (#55629)
8de37c3b152 is described below
commit 8de37c3b152d8aa3261e2ae5d44ba09a7867424d
Author: Shahar Epstein <[email protected]>
AuthorDate: Sat Sep 13 23:41:09 2025 +0300
Update i18n policy and related instructions for Release Managers
(2025-09-13) (#55629)
* Update i18n policy and related instructions for release managers
(2025-09-13)
* Update airflow-core/src/airflow/ui/public/i18n/README.md
Co-authored-by: Jens Scheffler <[email protected]>
---------
Co-authored-by: Jens Scheffler <[email protected]>
---
airflow-core/src/airflow/ui/public/i18n/README.md | 55 +++++++++++++++-----
dev/README_RELEASE_AIRFLOW.md | 63 ++++++++++++++++-------
2 files changed, 87 insertions(+), 31 deletions(-)
diff --git a/airflow-core/src/airflow/ui/public/i18n/README.md
b/airflow-core/src/airflow/ui/public/i18n/README.md
index 18e4d44284d..1d1c21f0a2a 100644
--- a/airflow-core/src/airflow/ui/public/i18n/README.md
+++ b/airflow-core/src/airflow/ui/public/i18n/README.md
@@ -61,11 +61,15 @@ communicating in the dev list or merging Pull Requests on
their behalf).
**Engaged translator** - Active contributor participating in translation
without formal ownership.
-**Inactive translation/code owner** — A translation/code owner is considered
inactive if they meet either of
+**Complete translation** - A supported locale is considered complete when it
covers at least 90% of the terms in the default locale.
+
+**Inactive owner** — Either a translation owner or a code owner might be
considered inactive if they meet any of
the following criteria:
- The locale under their responsibility has remained incomplete for at least 2
consecutive releases.
-- They have not participated in the Apache Airflow project for more than 12
months.
+- They have not contributed to Apache Airflow for more than 12 months.
+- Code owners specifically might be considered inactive according to any other
terms mentioned in the
+ ["Committers and PMC
Members"](../../../../../../COMMITTERS.rst#inactive-committers) document.
**Dev list** - The Apache Airflow development mailing list:
[email protected].
@@ -101,6 +105,8 @@ the following criteria:
- Code owners who act as translation sponsors are also responsible for:
- Ensuring that the translation owner is active and able to maintain the
translation.
- Act according to section 6.4 when the translation owner relinquishes their
role or become inactive.
+ - When they sponsor a single translation owner, without additional
translation owners/engaged translators involved,
+ they SHALL also review the language aspects of translation-related PRs
using a trusted third-party opinion (e.g., LLM).
### 4.3. Engaged translator
@@ -128,9 +134,11 @@ the following criteria:
owner.
- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by
the appropriate roles.
-> [!NOTE]
-> It is welcomed and desired to have more than one translation owner to enable
peer reviews and provide
-> coverage during absences.
+ > [!WARNING]
+ > It is preferred to have at least two translation owners, or at least one
translation owner and another engaged translator,
+ > to allow peer reviews and provide coverage during absences.
+ > Specifically, when translation is sponsored and there's only a single
translation owner, without additional proficient people involved, the code
owner becomes responsible for reviewing language aspects of PRs
+ > using a third-party opinion, which could risk quality and timeliness of
reviews.
### 5.2. Adding new locales
@@ -200,9 +208,10 @@ Translation conflicts MUST be resolved according to the
procedures outlined in s
### 6.1. Approval of ownership candidates
-- The designated code owner, should post a thread to the dev list, requesting
the approval of:
- - Introducing a new locale (including a link to the PR)
- - Translation owner(s) in the suggested locale for non committer candidates.
(sponsored)
+- The designated code owner should post a thread to the dev list that includes
the following details:
+ - The locale being suggested, including a link to the PR.
+ - Designated code owner(s) and translation owner(s) in the suggested locale.
+ - If the code owner is sponsored, they should indicate this as well.
Specifically, if there is only one translation owner, the code owner should
also declare how they plan to approve the language aspects of PRs (e.g., an
engaged translator, LLM, etc.).
- Within the thread, the code owner should demonstrate that the translation
owner is suitable for the role,
according to the requirements in section 5.3.
- Approval of any translation owner who is not a committer requires at least
one binding vote of 1 PMC member,
@@ -215,6 +224,7 @@ The following steps outline the process for approving a new
locale to be added t
- Creating a PR for adding the suggested locale to the
codebase ([see
example](https://github.com/apache/airflow/pull/51258/files)), which includes:
+ - Adding the plural form rules for the suggested locale under
`PLURAL_SUFFIXES` constant in `dev/i18n/check_translations_completeness.py`.
- The locale files (translated according to the guidelines) in the
`airflow-core/src/airflow/ui/public/i18n/locales/<LOCALE_CODE>` directory,
where `<LOCALE_CODE>` is the
code of the language according to ISO 639-1 standard (e.g., `fr` for
French). Languages with regional
@@ -283,7 +293,8 @@ Language proficiency for translation owners can be
demonstrated through any of t
(e.g., Portuguese vs. Spanish), the other language might be used as a
reference, but still the default
language (English) should be the primary source for translations.
- Translations should be accurate, maintaining original meaning and intent.
-- Translations should be complete, covering all terms and phrases in the
default language.
+- Translations should be complete, covering all terms and phrases in the
default language up to the defined
+ completeness threshold.
- Translation of technical terminology should be consistent (for example: Dag,
Task, Operator, etc.).
- Language should be polite and neutral in tone.
- Local conventions should be considered (e.g., date formats, number
formatting, formal vs. informal tone,
@@ -302,6 +313,10 @@ All files:
uv run dev/i18n/check_translations_completeness.py
```
+> [!NOTE]
+> When announcing a freeze time, copy the output of the table showing
completeness of all languages
+> to the mail body.
+
Files for specific languages:
```bash
@@ -350,13 +365,27 @@ FAIL_WHEN_ENGLISH_TRANSLATION_CHANGED = True
```
This fails any attempt to change English translation files in a PR unless
`allow translation change`
-label is applied to the PR. This allows to still fix critical issues in
English translation files and make
-deliberate updates to it but avoids accidental changes.
+label is applied to the PR. This still allows issues in the English
translation files to be fixed and
+deliberate updates to be made, while avoiding accidental changes.
-Any change in such English translation files during freeze time MUST be
communicated in the
-`#18n` Slack channel - so that translators can be informed as early as
possible about those translations
+Any change in the English translation files during freeze time MUST be
communicated in the
+[#18n](https://app.slack.com/client/TCQ18L22Z/C09D0A7FESJ?) Slack channel and
MUST be approved by at least 1 PMC member - so that translators can be informed
as early as possible about those translations
being added.
+> [!NOTE]
+> The definition of completeness takes into account that some terms might be
added during freeze time and remain untranslated.
+
+### 11.1 Guidelines for approving freeze exemptions
+
+The following questions should be considered before approving exemptions for
changes to the English translation files during freeze time:
+
+- Are the changes necessary for a critical fix or feature?
+- Do the changes only introduce minor fixes to existing terms? (such
modifications are usually less disruptive and OK to approve)
+- Do the changes introduce new terms, remove terms, or significantly alter
already translated terms? (if so, it may be better to wait until the next
release)
+- Is it feasible to complete the translations in all locales before the
release? (the fewer changes, the more feasible)
+- If not all translations are completed before the release, will it
significantly affect the user experience? (if so, it might be better to wait
until the next release).
+- If not all translations are completed before the release, will any locales
be left in an incomplete state? (if so, it might be better to wait until the
next release).
+
## 12. Exceptions
If any exceptions to this policy are needed, they MUST be discussed and
approved by voting in the dev list
diff --git a/dev/README_RELEASE_AIRFLOW.md b/dev/README_RELEASE_AIRFLOW.md
index 70374c64908..db9daec486a 100644
--- a/dev/README_RELEASE_AIRFLOW.md
+++ b/dev/README_RELEASE_AIRFLOW.md
@@ -21,7 +21,7 @@
**Table of contents**
- [Selecting what to put into the
release](#selecting-what-to-put-into-the-release)
- - [Validating completeness of i18n locale
files](#validating-completeness-of-i18n-locale-files)
+ - [Validating completeness of i18n locale files and announcing i18n freeze
time](#validating-completeness-of-i18n-locale-files-and-announcing-i18n-freeze-time)
- [Selecting what to cherry-pick](#selecting-what-to-cherry-pick)
- [Making the cherry picking](#making-the-cherry-picking)
- [Collapse Cadwyn Migrations](#collapse-cadwyn-migrations)
@@ -73,39 +73,52 @@ The first step of a release is to work out what is being
included. This differs
- For a *patch* release, you will be selecting specific commits to cherry-pick
and backport into the existing release branch.
-## Validating completeness of i18n locale files
+## Validating completeness of i18n locale files and announcing i18n freeze time
-At this point you should validate the completeness of the i18n locale files -
follow the instructions in section 8.1 of the [internationalization (i18n)
policy](../airflow-core/src/airflow/ui/public/i18n/README.md) for doing so.
-If there are any incomplete locales, copy the names of the incomplete locales
and send out a reminder to the code owners to ensure completion of the
translation by a due date of your choice
-before cutting the release candidate (RC).
-The reminder should be sent via [email protected] mailing list,
preferably with an accompanying GitHub issue for tracking purposes.
-Do not hold the release process beyond the due date if there are still
incomplete locales.
+> [!NOTE]
+> It is recommended to delegate all operations in this task to another
committer.
+
+Before cutting the release candidate (RC), you should announce a freeze time
for i18n changes to allow translators to complete translations for the upcoming
release without being overloaded by new terms, or other significant changes.
+The freeze should last at least one week, and until the RC is cut.
+It is recommended to announce the freeze at least two weeks before it starts.
+To prepare for the announcement, generate an output of completeness for all
locale files - follow the instructions in section 8.1 of the
[internationalization (i18n)
policy](../airflow-core/src/airflow/ui/public/i18n/README.md#81-checking-completeness-of-i18n-files)
for doing so.
+The reminder should be sent via [email protected] mailing list - you may
accompany it with a GitHub issue for tracking purposes.
+
+> [!NOTE]
+> When applicable - you should mention, within the output, translations that
have been incomplete in the past release,
+> and warn that they might be removed if they are not completed by the release
date.
Subject:
```shell script
cat <<EOF
-[REMINDER] Complete translations for Airflow ${VERSION} RC by <date>
+[ANNOUNCEMENT] English Translation freeze for Airflow ${VERSION} RC starting
at <START_DATE>
EOF
```
-Body:
+Body (assuming delegation to another committer):
```shell script
cat <<EOF
Hey fellow Airflowers,
-I'm planning to cut the Airflow ${VERSION} RC soon.
+I'm sending this message on behalf of the release managers.
+The release managers are planning to cut the Airflow ${VERSION} RC soon/by
<RELEASE_DATE>.
+
+After running the i18n completeness script, this is the coverage state of all
merged locales as of <CURRENT_DATE>:
-After running the i18n completeness script, I found that the following locales
are currently incomplete:
-<list of incomplete locales>
+<OUTPUT_OF_I18N_COMPLETENESS_SCRIPT>
-I'd like to ask locales' code owners to ensure the completion of the
translations for these locales by <due date>,
-and respond to this email after doing so.
-During this time, I'd like all committers to refrain merging PRs that add new
terms to the default locale (English),
-or rename/relocate keys of existing terms to avoid overloading the translators.
-When creating a PR, please run locally the i18n completeness script on your
locale to ensure all translations are complete.
-Changes applied after this date will not be included in the release, and the
missing terms will fall back to English instead.
+To prevent overloading the translators and to ensure completeness of all
translations by the release, a freeze upon the English locale will be applied
starting <START_DATE>,
+and until the RC is cut.
+Code owners, translation owners, and engaged translators are asked to complete
the coverage of their assigned locales during this time.
+
+Important notes:
+1. Any changes merged after the final release won't not be included, and
missing terms will fall back to English.
+2. Any PR that modifies the English locale during the freeze time will fail CI
checks.
+3. Requests for exemptions should be communicated in the #i18n Slack channel,
and approved by at least 1 PMC member - guidelines for approval are available
in the i18n policy.
+4. PRs approved for an exemption will be labeled with `allow translation
change`, and then the relevant CI check will pass. Translators are encouraged
to complete the translations for the exempted terms during the freeze time.
+5. Merging PRs for adding new translations could be done during the freeze
time - designated code owners should validate that by the end of the freeze
time, the coverage of the suggested translation is complete.
Thanks for your cooperation!
@@ -113,6 +126,20 @@ Thanks for your cooperation!
EOF
```
+When the freeze starts, you should merge a PR for setting the flag
`FAIL_WHEN_ENGLISH_TRANSLATION_CHANGED` to `True` in the file
[selective_checks.py](./breeze/src/airflow_breeze/utils/selective_checks.py).
+If the freeze gets extended, you should update the announcement thread
accordingly.
+When it is time to cut the RC, you should:
+
+1. Generate an additional completeness output:
+ a. If there are incomplete locales that were also incomplete in the previous
completeness output, please contact the code owner and ask them to act
according to section "Relinquishing translation/code ownership" in the i18n
policy (section 6.4).
+ b. If there are other incomplete locales, please write it as a reminder for
the next freeze announcement.
+2. Create a PR for setting the flag back to `False`.
+3. Post on the same thread that the freeze is lifted, and share the final
completeness output.
+
+> [!NOTE]
+> Release managers - do not hold the release process beyond the due date if
there are still incomplete locales after the freeze.
+> It is the responsibility of code owners to ensure the completeness of their
locales by the due date.
+
## Selecting what to cherry-pick
For obvious reasons, you can't cherry-pick every change from `main` into the
release branch -
