Update i18n freeze instructions

airflow-core/src/airflow/ui/public/i18n/README.md

@@ -66,7 +66,7 @@ communicating in the dev list or merging Pull Requests on their behalf).
 **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.
+- The locale under their responsibility has remained incomplete for at least 2 consecutive major/minor releases.
 - 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.
@@ -366,11 +366,11 @@ breeze ui check-translation-completeness --verbose --all-files
 
 ## 11. Freeze time
 
-Few weeks before a minor or major release, a freeze time for accepting new translations
-MUST be announced in the dev list, to allow time for testing and verification of translations.
+A few weeks before a minor or major release, a freeze time for accepting new translations, might be announced in the dev list by the Release Manager.
+It should be announced when the median coverage across all translations is below the completeness threshold (90%), or when needed (e.g., due to a critical UI feature that requires many new terms to be added).
+It will be announced in the dev list about two weeks before it starts, to allow time for preparing, and it should last until median completeness is back above the threshold, or RC is cut for the release (whichever is earlier).
 
-During that freeze time there should be no changes applied to the English translation source files
-by default. When freeze time starts we set this variable in the
+During that freeze time there should be no changes applied to the default language (English) locale files. When freeze time starts we set this variable in the
 `dev/breeze/src/airflow_breeze/utils/selective_checks.py` file:
 
 ```python

dev/README_RELEASE_AIRFLOW.md

@@ -22,7 +22,7 @@
 
 - [Perform review of security issues that are marked for the release](#perform-review-of-security-issues-that-are-marked-for-the-release)
 - [Selecting what to put into the release](#selecting-what-to-put-into-the-release)
-  - [Validating completeness of i18n locale files and announcing i18n freeze time](#validating-completeness-of-i18n-locale-files-and-announcing-i18n-freeze-time)
+  - [i18n workflow](#i18n-workflow)
   - [Selecting what to cherry-pick](#selecting-what-to-cherry-pick)
   - [Making the cherry picking](#making-the-cherry-picking)
   - [Collapse Cadwyn Migrations](#collapse-cadwyn-migrations)
@@ -86,20 +86,117 @@ 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 and announcing i18n freeze time
+## i18n workflow
 
 > [!NOTE]
-> It is recommended to delegate all operations in this task to another committer.
+>
+> 1. The instructions in this section should be applied only for major/minor releases.
+> 2. It is recommended to delegate all operations in this task to another committer.
+> 3. Except for the dev list announcements, it is recommended to communicate them via the #i18n Slack channel as well.
 
-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 dev@airflow.apache.org mailing list - you may accompany it with a GitHub issue for tracking purposes.
+### Validating completeness of locale files
 
-> [!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.
+Before cutting the release candidate (RC), you should verify the completeness of all merged locale files.
+Generate a completeness output 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) to do so.
+
+#### Patch releases (v3-X-test branch)
+
+For patch releases, post a reminder to the dev@airflow.apache.org list to complete missing phrases against the v3-X-test branch.
+
+Subject:
+
+```shell script
+[REMINDER] i18n phrases for Airflow ${VERSION} patch release (v${VERSION_BRANCH}-test)
+```
+
+Body (assuming delegation to another committer):
+
+```shell script
+cat <<EOF
+Hey fellow Airflowers,
+
+I'm sending this reminder on behalf of the release managers.
+We plan to cut the Airflow ${VERSION} RC soon/by <RELEASE_DATE> from v${VERSION_BRANCH}-test.
+
+After running the i18n completeness script against the v${VERSION_BRANCH}-test branch, here is the current coverage across merged locales as of <CURRENT_DATE>:
+
+<OUTPUT_OF_I18N_COMPLETENESS_SCRIPT>
+
+Translation owners and engaged translators are kindly asked to add missing phrases in the v3-<X>-test branch ahead of the RC.
+
+Notes:
+1. Changes merged after the final patch release won't be included, and missing terms will fall back to English.
+2. Please coordinate via the #i18n Slack channel if you need assistance or expect terminology changes.
+3. Keep PRs small and focused to minimize review time on the patch branch.
+
+Thanks for your cooperation!
+<your name>
+EOF
+```
+
+When it is time to cut the RC:
+
+- Regenerate the completeness output against v${VERSION_BRANCH}-test.
+- Post the final completeness output on the same thread.
+
+#### Minor/Major releases
+
+If the median completeness across all supported languages is below 90%, or upon other justifying circumstances (e.g., release of a critical UI feature), you should consider skipping the following instructions and applying an i18n translation freeze instead (see subsection below).
+Otherwise, you should announce the completeness status to the dev@airflow.apache.org mailing list.
+
+Subject:
+
+```shell script
+[ANNOUNCEMENT] i18n completeness check for Airflow ${VERSION} RC
+```
+
+Body (assuming delegation to another committer):
+
+
+```shell script
+cat <<EOF
+Hey fellow Airflowers,
+
+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>:
+
+<OUTPUT_OF_I18N_COMPLETENESS_SCRIPT>
+
+Code owners, translation owners, and engaged translators whose locales are currently below 90% coverage are kindly asked to complete their translations prior to the RC being cut.
+This will help ensure that all languages included in the upcoming release remain complete and consistent.
+
+Contributors are also encouraged to plan their PRs accordingly and avoid introducing large sets of new English terms close to the release date, to prevent unexpected translation work for code owners.
+
+Important notes:
+1. Locales that remain incomplete for two consecutive major or minor releases may be removed from the project, according to the i18n policy.
+2. Any changes merged after the final release won't be included, and missing terms will fall back to English.
+3. Code owners are responsible for ensuring that their assigned locales reach at least 90% coverage before the RC is cut.
+4. Requests for assistance, coordination, or early heads-up on expected terminology changes may be shared in the #i18n Slack channel.
+5. PRs introducing new translations may continue to be merged as usual, provided that coverage remains complete by the RC date.
+
+Thanks for your cooperation!
+<your name>
+EOF
+```
+
+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 major/minor release, 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 major/minor release.
+2. Post the final completeness output on the same thread.
+
+### Applying an i18n translation freeze
+
+Before cutting the release candidate (RC), you may announce a freeze time to allow translators to complete translations for the upcoming release.
+During the freeze time, no changes to the English locale file should be merged (enforced by CI checks), except for approved exemptions (see below).
+In general, if the overall median coverage across all supported languages stays above 90%, a freeze is not required. However, if significant changes are introduced that lower the median coverage to or below this threshold, a freeze period can help translators complete their work without being overloaded.
+When a freeze is used, it should remain in effect until the median coverage reaches at least 90% again, or until the RC is cut, whichever comes first.
+The freeze should be announced at least two weeks before it starts, to allow time for translators to get ready and for contributors to plan their PRs accordingly.
+To prepare for the announcement, fetch the completeness output generated earlier.
+The announcement should be sent via the dev@airflow.apache.org mailing list – you may accompany it with a GitHub issue for tracking purposes.
 
 Subject:
 
@@ -125,13 +222,15 @@ After running the i18n completeness script, this is the coverage state of all me
 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.
+Contributors are also encouraged to plan their PRs accordingly, to avoid modifying the English locale during the freeze 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.
+1. Locales that remain incomplete for two consecutive major or minor releases may be removed from the project, according to the i18n policy.
+2. Any changes merged after the final release won't be included, and missing terms will fall back to English.
+3. Any PR that modifies the English locale during the freeze time will fail CI checks.
+4. 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.
+5. 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.
+6. 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!
@@ -140,12 +239,12 @@ 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.
+If the freeze gets extended beyond the originally announced date, you should post an update on the same thread.
 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.
+  b. If there are other incomplete locales, please write it as a reminder for the next major/minor release.
 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.
 

dev/breeze/src/airflow_breeze/commands/ui_commands.py

@@ -663,18 +663,29 @@ def check_translation_completeness(
         if coverage_per_language:
             from rich.table import Table
 
+            def get_coverage_str(coverage: float) -> str:
+                if coverage >= 95:
+                    return f"[bold green]{coverage:.1f}%[/bold green]"
+                if coverage > 90:
+                    return f"[bold yellow]{coverage:.1f}%[/bold yellow]"
+                return f"[red]{coverage:.1f}%[/red]"
+
             summary_table = Table(show_header=True, header_style="bold magenta")
             summary_table.title = "Total Coverage per Language"
             summary_table.add_column("Language", style="cyan")
             summary_table.add_column("Coverage", style="green")
             for lang, coverage in sorted(coverage_per_language.items()):
-                if coverage >= 95:
-                    coverage_str = f"[bold green]{coverage:.1f}%[/bold green]"
-                elif coverage > 80:
-                    coverage_str = f"[bold yellow]{coverage:.1f}%[/bold yellow]"
+                summary_table.add_row(lang, get_coverage_str(coverage))
+            # Calculate and print median coverage
+            coverages = sorted(coverage_per_language.values())
+            n = len(coverages)
+            if n > 0:
+                if n % 2 == 1:
+                    median_coverage = coverages[n // 2]
                 else:
-                    coverage_str = f"[red]{coverage:.1f}%[/red]"
-                summary_table.add_row(lang, coverage_str)
+                    median_coverage = (coverages[n // 2 - 1] + coverages[n // 2]) / 2
+                summary_table.add_row("", "", end_section=True)
+                summary_table.add_row("Median", get_coverage_str(median_coverage))
             console.print(summary_table)