You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "shahar1 (via GitHub)" <gi...@apache.org> on 2026/04/21 21:21:58 UTC
[PR] Simplify i18n policy [airflow]
shahar1 opened a new pull request, #65630:
URL: https://github.com/apache/airflow/pull/65630
<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->
<!--
Thank you for contributing!
Please provide above a brief description of the changes made in this pull request.
Write a good git commit message following this guide: http://chris.beams.io/posts/git-commit/
Please make sure that your code changes are covered with tests.
And in case of new features or big changes remember to adjust the documentation.
Feel free to ping (in general) for the review if you do not see reaction for a few days
(72 Hours is the minimum reaction time you can expect from volunteers) - we sometimes miss notifications.
In case of an existing issue, reference it using one of the following:
* closes: #ISSUE
* related: #ISSUE
-->
I created the i18n policy just before LLM agents started to pop up, so most of the things that were issues before - are now none (for example, no need for "freeze time" - you just ask the LLM to translate whatever you need).
I used ChatGPT to simplify the policy - and it seems to achieve what we want in half of the original size :)
Will be merged after approval & lazy consensus in the dev list.
---
##### Was generative AI tooling used to co-author this PR?
<!--
If generative AI tooling has been used in the process of authoring this PR, please
change below checkbox to `[X]` followed by the name of the tool, uncomment the "Generated-by".
-->
- [X] Yes (please specify the tool below)
ChatGPT 5.4
<!--
Generated-by: [Tool Name] following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
-->
---
* Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)** for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
* For fundamental code changes, an Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals)) is needed.
* When adding dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
* For significant user-facing changes create newsfragment: `{pr_number}.significant.rst`, in [airflow-core/newsfragments](https://github.com/apache/airflow/tree/main/airflow-core/newsfragments). You can add this file in a follow-up commit after the PR is created so you know the PR number.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120417601
##########
.pre-commit-config.yaml:
##########
@@ -601,6 +601,7 @@ repos:
^README\.md$|
^pyproject\.toml$|
^generated/PYPI_README\.md$|
+ ^airflow-core/src/airflow/ui/public/i18n/README\.md$|
Review Comment:
he he he
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3121806523
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
Review Comment:
Added as a manual instruction, could be later automated with an appropriate agent skill
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
Review Comment:
Added as a manual instruction for that, could be later automated with an appropriate agent skill
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120422438
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
+recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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 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
-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 still allows issues in the English translation files to be fixed and
-deliberate updates to be made, while avoiding accidental changes.
-
-Any change in the English translation files during freeze time MUST be communicated in the
-[#i18n](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
-beforehand.
-
-## 13. Review and updates
-
-This policy will be reviewed and updated as needed to ensure it remains relevant and effective.
-Depending on the nature of the change, suggested updates might need to be discussed and approved by voting in
-the dev list.
+## Locale-specific guidance
+
+Before translating, read the locale-specific guide if one exists. Those files contain glossary and style choices
+for the target language and override the general guidance in this document when there is a conflict. They are
+primarily intended for LLM-assisted translation work, but can also be used by human contributors.
+
+| Locale Code | Language | Guideline File |
Review Comment:
I don't mind :)
When we get to the point of over 200 languages, I'll think of an automation (currently ChatGPT handles it very well)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "bbovenzi (via GitHub)" <gi...@apache.org>.
bbovenzi merged PR #65630:
URL: https://github.com/apache/airflow/pull/65630
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3121822392
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
Review Comment:
Should have been "translation owner" in that context, fixed.
I prefer to avoid getting deeper into more definitions as the idea is to simplify this policy - any contributor who knows the language and want to review PRs, they're welcome :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "pierrejeambrun (via GitHub)" <gi...@apache.org>.
pierrejeambrun commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3123651046
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,206 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
+> This policy currently applies only to Airflow core UI translations.
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
+## Core terms
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+## Ownership
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+Each supported non-English locale must have:
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+Having more than one translation owner for a locale is recommended, but not required.
-- 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.
+## Communication
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation-related decisions that affect supported locales, ownership, or policy should happen in public
+through the dev list.
-## 3. Wording/Phrasing
+Locale owners and other regular translation contributors should also join the `#i18n` Slack channel for
+day-to-day coordination and for release-time notifications about last-minute string changes.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
+- The locale owners are prepared to coordinate in the `#i18n` Slack channel for ongoing translation work and
+ release-time notifications.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- A locale-specific translation guide file at `.github/skills/airflow-translations/locales/<locale>.md`
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing translation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers' votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner resolves language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages, languages with significantly different word order, or languages that typically require much longer text, a UI check is strongly recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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).
Review Comment:
This section about freeze period + completeness threshold have been completely remove. Is that intentional?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "jscheffl (via GitHub)" <gi...@apache.org>.
jscheffl commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120413190
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
+recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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 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
-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 still allows issues in the English translation files to be fixed and
-deliberate updates to be made, while avoiding accidental changes.
-
-Any change in the English translation files during freeze time MUST be communicated in the
-[#i18n](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
-beforehand.
-
-## 13. Review and updates
-
-This policy will be reviewed and updated as needed to ensure it remains relevant and effective.
-Depending on the nature of the change, suggested updates might need to be discussed and approved by voting in
-the dev list.
+## Locale-specific guidance
+
+Before translating, read the locale-specific guide if one exists. Those files contain glossary and style choices
+for the target language and override the general guidance in this document when there is a conflict. They are
+primarily intended for LLM-assisted translation work, but can also be used by human contributors.
+
+| Locale Code | Language | Guideline File |
Review Comment:
You are sure you want to maintain this table (if languages are added/removed)?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120780695
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
+recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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 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
-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 still allows issues in the English translation files to be fixed and
-deliberate updates to be made, while avoiding accidental changes.
-
-Any change in the English translation files during freeze time MUST be communicated in the
-[#i18n](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
-beforehand.
-
-## 13. Review and updates
-
-This policy will be reviewed and updated as needed to ensure it remains relevant and effective.
-Depending on the nature of the change, suggested updates might need to be discussed and approved by voting in
-the dev list.
+## Locale-specific guidance
+
+Before translating, read the locale-specific guide if one exists. Those files contain glossary and style choices
+for the target language and override the general guidance in this document when there is a conflict. They are
+primarily intended for LLM-assisted translation work, but can also be used by human contributors.
+
+| Locale Code | Language | Guideline File |
Review Comment:
To be honest @jscheffl . those are now almost self maintained when you use agents - they will notice and correct every time things are touched.
But yes - I would still try to automate that part regardless. I think those things cost token and anything that **can** be deterministicly verified byfore PUSH - **should still be**
We should only really rely on AI for things that cannot be easily automated with determistic code - I found that - in those cases - using AI to generate the code to keep things in check is the best of both world. You use the tokens only once.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3121542398
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
Review Comment:
IMHO "reviewer" (or "active reviewer") requires a definition under the core terms, especially now that "engaged translator" is gone.
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
+recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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 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
-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 still allows issues in the English translation files to be fixed and
-deliberate updates to be made, while avoiding accidental changes.
-
-Any change in the English translation files during freeze time MUST be communicated in the
-[#i18n](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
-beforehand.
-
-## 13. Review and updates
-
-This policy will be reviewed and updated as needed to ensure it remains relevant and effective.
-Depending on the nature of the change, suggested updates might need to be discussed and approved by voting in
-the dev list.
+## Locale-specific guidance
+
+Before translating, read the locale-specific guide if one exists. Those files contain glossary and style choices
+for the target language and override the general guidance in this document when there is a conflict. They are
+primarily intended for LLM-assisted translation work, but can also be used by human contributors.
+
+| Locale Code | Language | Guideline File |
Review Comment:
@jscheffl who maintains the table aside - this should be useful for LLMs to know where to look for additional instructions.
##########
dev/README_RELEASE_AIRFLOW.md:
##########
@@ -203,73 +202,12 @@ 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).
+ 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 the [removing or replacing ownership procedure](../airflow-core/src/airflow/ui/public/i18n/README.md#removing-or-replacing-ownership) in the i18n policy.
Review Comment:
Perhaps we should mentioned the preferred way to contact? E.g. slack, devlist, tag in PR, approach in person at the Airflow Summit, etc.
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
Review Comment:
```suggestion
### Relinquishing translation/code ownership
```
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
Review Comment:
Or languages where the translated string has a significantly different number of characters (especially when it's longer)?
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
Review Comment:
```suggestion
- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers' votes counted as binding.
```
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
Review Comment:
Depending on what you meant:
```suggestion
- A translation owner resolves language questions for their locale.
```
```suggestion
- A translation owner has the final say on language questions for their locale.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "pierrejeambrun (via GitHub)" <gi...@apache.org>.
pierrejeambrun commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3123651046
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,206 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
+> This policy currently applies only to Airflow core UI translations.
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
+## Core terms
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+## Ownership
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+Each supported non-English locale must have:
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+Having more than one translation owner for a locale is recommended, but not required.
-- 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.
+## Communication
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation-related decisions that affect supported locales, ownership, or policy should happen in public
+through the dev list.
-## 3. Wording/Phrasing
+Locale owners and other regular translation contributors should also join the `#i18n` Slack channel for
+day-to-day coordination and for release-time notifications about last-minute string changes.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
+- The locale owners are prepared to coordinate in the `#i18n` Slack channel for ongoing translation work and
+ release-time notifications.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- A locale-specific translation guide file at `.github/skills/airflow-translations/locales/<locale>.md`
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing translation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers' votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner resolves language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages, languages with significantly different word order, or languages that typically require much longer text, a UI check is strongly recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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).
Review Comment:
This section about freeze period + completeness threshold have been completely remove. Is that intentional?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3121861363
##########
dev/README_RELEASE_AIRFLOW.md:
##########
@@ -203,73 +202,12 @@ 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).
+ 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 the [removing or replacing ownership procedure](../airflow-core/src/airflow/ui/public/i18n/README.md#removing-or-replacing-ownership) in the i18n policy.
Review Comment:
Added a communications section at the top
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120422438
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
+recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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 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
-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 still allows issues in the English translation files to be fixed and
-deliberate updates to be made, while avoiding accidental changes.
-
-Any change in the English translation files during freeze time MUST be communicated in the
-[#i18n](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
-beforehand.
-
-## 13. Review and updates
-
-This policy will be reviewed and updated as needed to ensure it remains relevant and effective.
-Depending on the nature of the change, suggested updates might need to be discussed and approved by voting in
-the dev list.
+## Locale-specific guidance
+
+Before translating, read the locale-specific guide if one exists. Those files contain glossary and style choices
+for the target language and override the general guidance in this document when there is a conflict. They are
+primarily intended for LLM-assisted translation work, but can also be used by human contributors.
+
+| Locale Code | Language | Guideline File |
Review Comment:
I don't mind :)
When we get to the point of over 200 languages, I'll think of an automation
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
+recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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 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
-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 still allows issues in the English translation files to be fixed and
-deliberate updates to be made, while avoiding accidental changes.
-
-Any change in the English translation files during freeze time MUST be communicated in the
-[#i18n](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
-beforehand.
-
-## 13. Review and updates
-
-This policy will be reviewed and updated as needed to ensure it remains relevant and effective.
-Depending on the nature of the change, suggested updates might need to be discussed and approved by voting in
-the dev list.
+## Locale-specific guidance
+
+Before translating, read the locale-specific guide if one exists. Those files contain glossary and style choices
+for the target language and override the general guidance in this document when there is a conflict. They are
+primarily intended for LLM-assisted translation work, but can also be used by human contributors.
+
+| Locale Code | Language | Guideline File |
Review Comment:
I don't mind :)
When we get to the point of over 200 languages, I'll think of an automation (currnently ChatGPT handles it very well)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120410512
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
+recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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 default language (English) locale files. When freeze time starts we set this variable in the
Review Comment:
The translation freeze capability could also be removed from breeze, I'll take care of it later.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #65630:
URL: https://github.com/apache/airflow/pull/65630#issuecomment-4297947392
### Backport successfully created: v3-2-test
Note: As of [Merging PRs targeted for Airflow 3.X](https://github.com/apache/airflow/blob/main/dev/README_AIRFLOW3_DEV.md#merging-prs-targeted-for-airflow-3x)
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.
In matter of doubt please ask in [#release-management](https://apache-airflow.slack.com/archives/C03G9H97MM2) Slack channel.
<table>
<tr>
<th>Status</th>
<th>Branch</th>
<th>Result</th>
</tr>
<tr>
<td>✅</td>
<td>v3-2-test</td>
<td><a href="https://github.com/apache/airflow/pull/65678"><img src="https://img.shields.io/badge/PR-65678-blue" alt="PR Link"></a></td>
</tr>
</table>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120772593
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
-### 4.2. Code owner
+The PR for a new locale should include:
-- Code owners are responsible for the following, in their assigned supported locale, according to the
- procedures stated below:
- - Reviewing the technical aspects of translation-related PRs (e.g., linting, formatting, etc.).
- - Merging translation-related PRs approved by the translation owner.
- - Resolving translation-related conflicts in PRs, when there's a conflict between translation owners.
- - Managing translation-related GitHub issues and discussions, when needed (e.g., closing GitHub issues).
-- 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 becomes 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).
+- Locale files under `airflow-core/src/airflow/ui/public/i18n/locales/<locale>`.
+- Updates to `airflow-core/src/airflow/ui/src/i18n/config.ts`.
+- Updates to `dev/breeze/src/airflow_breeze/commands/ui_commands.py`.
+- Updates to `.github/CODEOWNERS`.
+- Updates to the table at the bottom of this file.
-### 4.3. Engaged translator
+### Relinquishing ranslation/code ownership
-- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to
- supported locales by:
- - Suggesting improvements.
- - Reviewing PRs.
- - Reporting issues or inconsistencies in translations.
- - Participating in discussions related to translations.
- - Assisting translation owners with their tasks.
- - Being 3rd party reviewers for translation-related conflicts, when needed.
-- Engaged translators may be mentioned in a comment in the `.github/CODEOWNERS` file.
-- Suitable candidates for translation ownership may be suggested from engaged translators, upon their consent
- and approval by the procedure in section 6.1.
-
-## 5. Requirements
-
-### 5.1. Translation ownership and code ownership
+- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
-- Each supported locale, except for the default language, MUST have at least one translation owner and at
- least one code owner assigned at all times, with these considerations:
- - Ownership for both roles MUST be approved according to the process discussed in section 6.1.
- - A single Apache Airflow committer MAY serve as both code owner and translation owner for the same locale.
- - If none of the translation owners are code owners - there MAY be a translation sponsor assigned as a code
- owner.
-- When the above is not met, steps mentioned in section 6.4 SHOULD be taken by the appropriate roles.
+ - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
+ - Post a thread in the dev list that they step in as the code owner.
- > [!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.
+- When a translation owner asks to relinquish their role, or they become inactive, and there are no other active translation owners, the code owner should:
-### 5.2. Adding new locales
+- Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+- Post a thread in the dev list that they are looking for assigning someone else as the translation owner within 30 days.
+- If a replacement is found within this time, they should be approved according to the ownership approval procedure below.
+- Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the codebase, with PMC and committers votes counted as binding.
-To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section
-6.2.
+## Procedures
-### 5.3. Translation owners candidates
+### Approval of ownership candidates
-- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target
- language for translation purposes, including technical terminology (as detailed in section 6.5).
-- Translation owners candidates, who are non-committers, MUST also meet the following criteria:
- - They are active long-term contributors to the Apache Airflow project at the time of request.
- - They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within
- their target language.
- - They have the support of an Apache Airflow committer who will act as a translation sponsor.
-
-### 5.4. Resolution of translation conflicts
-
-Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
-
-### 5.5. Adding or rephrasing terms
-
-- When new terms are added to the default locale, all translation owners SHOULD create a follow-up PR to
- comply with the changes in their assigned locale.
-- When existing terms are rephrased in the default language (key is the same but value changed), all
- translation owners SHOULD do the same as above.
-- As the change of the default language might be un-noticed by translators (translation keys would stay valid)
- it is recommended to rename the translation key to force a detection of language gaps (translations would
- have 1 orphan (old) key and a missing (new) key).
-- In busy times with many parallel UI changes it is acceptable to batch changes together. Differences SHOULD
- be cleared prior to a release at the latest.
+- 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.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role.
+- Approval of any translation owner who is not a committer requires at least one binding vote of 1 PMC member, and no objections from other committers or PMC.
+- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
-> [!NOTE]
-> Tooling for detecting missing terms is available (see Tools & Resources section below).
+## Expectations for translation changes
-### 5.6. Deprecating / refactoring terms
+### Default locale changes
-- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value
- unchanged), **the contributor initiating the change is responsible for updating all relevant locale
- files, and not any of the locale's owners**. When such is available, automation through Breeze tooling SHOULD
- be used.
+English is the source of truth. When contributors add, rename, or substantially rephrase English terms, they
+should make downstream translation work easy.
-### 5.7. Merging of translation-related Pull Requests (PRs)
+- New or materially changed strings should be easy to detect in other locales.
+- If a key is rephrased significantly, renaming the key is preferred so missing translations are visible.
+- If a key is only moved or renamed without changing meaning, the contributor making that refactor should update
+ the locale files rather than leaving cleanup to translation owners.
+- In some cases, it may be more cost-effective to update the non-English locales in the same PR as the default-locale change, for example by using LLM-assisted translation. In that case, separate explicit approval from translation owners or code owners for each locale update is not required.
-- Before merging any translation-related PR, it MUST be:
- - Approved by a translation owner of the respective locale for language aspects, according to the standards
- and guidelines.
- - When a translation owner initiates a PR and is the only one assigned to the locale, they SHOULD instead
- ask for approval from a third party (e.g., engaged translator), or if such is not available, declare
- their self-approval for the language aspects.
- - Approved by a code owner, or another committer on their behalf, for technical aspects (e.g., linting,
- formatting, etc.).
-- Before merging a translation-related PR, the translation SHOULD be checked for completeness using the
- provided tools (see section 8).
+### Non-Default locale changes
-> [!WARNING]
-> In languages with different word order than English, or in Right-To-Left (RTL) languages, it is important to
-> validate that the changes are properly reflected in the UI.
-> If they are not, please raise a GitHub issue or a PR for fixing it (separately from the translation PR).
+Translations should:
-### 5.8. Version release
+- Preserve the meaning and intent of the English source.
+- Keep technical terminology consistent.
+- Preserve placeholders, formatting, and interpolation variables.
+- Follow local language conventions without changing product behavior.
+- Stay at or above the completeness threshold over time.
-- Release managers MUST follow the requirements for releasing changes in supported locales defined in
- the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+Locale-specific guideline files take precedence over the general guidance in this document.
-## 6. Procedures
+> [!CAUTION]
+> Translation content must comply with the Apache Airflow Code of Conduct.
-### 6.1. Approval of ownership candidates
+## Review and merge expectations
-- 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,
- and no objections from other committers/PMC.
-- Approval of any translation owner who is also a code owner (committer) does not need to be voted on.
+Before merging a translation-related PR:
-### 6.2. Approval of a new locale
-
-The following steps outline the process for approving a new locale to be added to the supported locales:
-
-- 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/breeze/commands/ui_commands.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
- variants should be handled in separate directories, where the name is suffixed with `-<VARIANT>`, and
- `<VARIANT>` is the variant that follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for
- Taiwanese Mandarin).
- - Making the required modifications in
- `airflow-core/src/airflow/ui/src/i18n/config.ts` ([see example](https://github.com/apache/airflow/pull/51258/files#diff-bfb4d5fafd26d206fb4a545a41ba303f33d15a479d21e0a726fd743bdf9717ff)).
- - Changes to the `.github/CODEOWNERS` file to include the designated code owner(s) and translation owner(s)
- for the new locale, considering the following:
- - A code owner who is also a translation sponsor should be indicated in a comment as well.
- - If the PR author is neither eligible nor willing to become both of these roles, they should suggest
- relevant candidates for the missing role(s), or call for volunteers.
-- Applying the procedure in section 6.1. to approve the identities of the code owner(s) and the translation
- owner(s).
-- Only after the steps above are completed, the PR for the new translation may be merged (by the requirements
- in section 5.7).
-- Translation owners and code owners for the new locale SHOULD add themselves to the `#i18n` channel of
- Airflow slack - during freeze time this is where notification about new "last-minute" changes to translation
- files will be published, also it's a great platform to collaborate and share internationalization tips and
- tricks.
-
-### 6.3. Translation conflict resolution
-
-When a translation conflict arises in a locale-related PR, the following steps will be taken in order:
-
-- The involved parties should first try to reach a consensus through discussion in the PR.
-- If no consensus is reached, a translation owner may decide the outcome.
-- If multiple translation owners are involved and cannot reach consensus, the code owner will decide. If the
- code owner is sponsored,
- they should base their decision on a neutral source (e.g., a third-party opinion, translation tool, or LLM).
-- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
-
-### 6.4. Relinquishing translation/code ownership
+- Language changes should be approved by a translation owner for that locale.
+- Technical changes may be approved and merged by any committer. However, the code owner has an added responsibility for the locale, so it is preferable to involve them.
+- Completeness should be checked with the available tooling.
-- When a code owner asks to relinquish their role, or they become inactive, any other committer should:
- - Raise a PR for removal of the previous code owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they step in as the code owner (either as a translation sponsor, or a
- translation owner according to steps discussed in section 6.1).
-- When a translation owner asks to relinquish their role, or they become inactive, and there are no other
- active translation owners, the code owner should:
- - Raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
- - Post a thread in the dev list that they are looking for assigning someone else as the translation owner
- within 30 days.
- - If a replacement is found within this time, they should be approved according to section 6.1.
- - Otherwise, the code owner should raise a vote in the dev list for the removal of the translation from the
- codebase (7 days vote, PMC and committers votes are counted as binding).
+If a locale has only one translation owner and that person authors the PR, an additional reviewer is preferred.
+When that is not practical, the code owner may use a trusted third-party review method, including LLM-assisted
+review, before merging (for example, GitHub Copilot or Claude).
-### 6.5 Demonstrating language proficiency
+When a translation dispute cannot be resolved in the PR discussion:
-Language proficiency for translation owners can be demonstrated through any of the following means:
+- A translation owner decides language questions for their locale.
+- If multiple translation owners disagree, the code owner decides.
+- If code owners disagree, a PMC member should be involved to resolve the conflict.
-- Communications in open-source projects, social media, mailing lists, forums, or any other platforms in the
- target language.
-- Direct communication with a proficient committer in the target language.
-- Official language certifications (this is not a mandatory requirement).
+For RTL languages or languages with significantly different word order, a UI check is strongly
+recommended in addition to file-level review.
-## 7. Standards & guidelines
+## Tools
-> [!CAUTION]
-> Usage of language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/)
-> is prohibited in any circumstances.
-
-- Translations should be based on the default language (English). When translating a language that has already
- a similar translation supported
- (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 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,
- etc.).
- - In case that local conventions requires deviation from any of these guidelines, exceptions may be
- requested via PR or a thread in the dev list.
-- Formatting, placeholders, and variable substitutions must be preserved.
-
-## 8. Tools & resources
-
-### 8.1. Checking completeness of i18n files
-
-All files:
+Check completeness for all locales:
```bash
breeze ui check-translation-completeness
```
-> [!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:
+Check a specific locale:
```bash
breeze ui check-translation-completeness --language <language_code>
```
-Where `<language_code>` is the code of the language you want to check, e.g., `en`, `fr`, `de`, etc.
-
-Adding missing translations (with `TODO: translate` prefix):
+Add missing entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --add-missing
```
-You can also remove unused translations from the language of your choice:
+Remove unused entries for a locale:
```bash
breeze ui check-translation-completeness --language <language_code> --remove-unused
```
-Or from all languages:
+Remove unused entries for all locales:
```bash
breeze ui check-translation-completeness --remove-unused
```
-
-## 9. Compliance & enforcement
-
-> [!NOTE]
-> As of the time of writing, this policy is not enforced by any automated checks.
-> The following describe the desired future state of compliance and enforcement.
-
-- Automated checks SHOULD verify once in a while that all languages have corresponding entries for new terms
- in the default language. When translations are missing, relevant code owners should be notified.
-- Automated checks SHOULD allow a person doing translation to select the language and aid them in adding new
- translations so that they do not have to compare them manually. Possibly it can be done by adding
- `-–add-missing` to the verifying script that will add new entries with `TODO: translate: ENGLISH VERSION`
- and add prek hook to not allow such `TODO:` entries to be committed.
-
-## 11. Freeze time
-
-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 default language (English) locale files. When freeze time starts we set this variable in the
Review Comment:
Indeed :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "jscheffl (via GitHub)" <gi...@apache.org>.
jscheffl commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120415530
##########
.pre-commit-config.yaml:
##########
@@ -601,6 +601,7 @@ repos:
^README\.md$|
^pyproject\.toml$|
^generated/PYPI_README\.md$|
+ ^airflow-core/src/airflow/ui/public/i18n/README\.md$|
Review Comment:
Haha, sounds like you don't want to be inclusive in your language? :-D
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Simplify i18n policy [airflow]
Posted by "jscheffl (via GitHub)" <gi...@apache.org>.
jscheffl commented on code in PR #65630:
URL: https://github.com/apache/airflow/pull/65630#discussion_r3120408457
##########
airflow-core/src/airflow/ui/public/i18n/README.md:
##########
@@ -19,387 +19,196 @@
# Internationalization (i18n) Policy
-## 1. Purpose & scope
+## Purpose and scope
-This document outlines the policy for internationalization (i18n) in Apache Airflow, detailing the lifecycle
-of translations within the project.
-This policy aims to avoid inconsistencies, maintenance issues, unclear ownership, and to ensure translation
-quality.
+This document defines the minimal policy for UI translations in Apache Airflow core. It exists to keep
+translations maintainable, reviewable, and consistent without adding unnecessary process.
-### Scope
+It applies to:
-This policy applies to:
-
-- Each supported locale included in `airflow-core/src/airflow/ui/public/i18n/locales`.
-- Contributors making changes in the default locale (English).
-- Contributors suggesting new locales to be added to the codebase.
-- Maintainers of supported locales in any role defined below.
-- Committers and PMC.
-- Release managers.
+- All supported locales in `airflow-core/src/airflow/ui/public/i18n/locales`.
+- Contributors changing the default locale (`en`).
+- Contributors proposing a new supported locale.
+- Translation owners, code owners, and committers reviewing translation-related PRs.
> [!NOTE]
-> This policy currently applies only to changes made in Apache Airflow core, as i18n is not yet implemented
-> for providers (including auth managers). When such support is added, this policy should be updated to reflect
-> the expanded scope.
-
-## 2. Definitions
-
-**Internationalization (i18n)** - The process of designing a software application so that it can be adapted to
-various languages and regions without engineering changes (see also
-the [Wikipedia article](https://en.wikipedia.org/wiki/Internationalization_and_localization)).
-
-**Supported locale** - An officially accepted locale in `airflow-core/src/airflow/ui/public/i18n/locales`.
-
-**Default locale** - English (`en`), the primary locale and fallback for all other locales.
-
-**Translation owner** - Designated contributor responsible for maintaining a supported locale.
+> This policy currently applies only to Airflow core UI translations.
-**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+## Core terms
-**Translation sponsor** - Apache Airflow committer supporting a non-committer translation owner (e.g., by
-communicating in the dev list or merging Pull Requests on their behalf).
+- **Default locale**: English (`en`), the source and fallback for all other locales.
+- **Supported locale**: A locale that is present in the repository and listed in the UI configuration.
+- **Translation owner**: The person responsible for language quality and ongoing maintenance of a supported locale.
+- **Code owner**: The committer responsible for technical review and merge decisions for that locale.
+- **Translation sponsor**: A committer supporting a non-committer translation owner.
+- **Complete translation**: A locale that covers at least 90% of the terms in the default locale.
-**Engaged translator** - Active contributor participating in translation without formal ownership.
+## Ownership
-**Complete translation** - A supported locale is considered complete when it covers at least 90% of the terms in the default locale.
+Each supported non-English locale must have:
-**Inactive owner** — Either a translation owner or a code owner might be considered inactive if they meet any of
-the following criteria:
+- At least one translation owner.
+- At least one code owner listed in `.github/CODEOWNERS`.
-- 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.
+A single committer may serve in both roles. When the translation owner is not a committer, a committer must
+act as translation sponsor.
-**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+Translation owners are responsible for language quality, consistency, and keeping the locale reasonably current.
+Code owners are responsible for technical review, merge decisions, and making sure the locale still has active
+maintainers.
-## 3. Wording/Phrasing
+Having more than one active reviewer for a locale is recommended, but not required.
-- Unless explicitly stated otherwise, all references to directories and files in this document pertain to
- those in the `main` branch.
-- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
- SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
- RFC 2119.
+## Adding or removing a supported locale
-## 4. Roles & responsibilities
+### Adding a locale
-### 4.1. Translation owner
+A new locale may be added when all of the following are true:
-- Translation owners are responsible for the following, in their assigned supported locale, according to the
- established quality standards and procedures stated below:
- - Ensuring locale remains up-to-date with source code changes in the default locale.
- - Reviewing the language aspects of translation-related Pull Requests (PRs).
- - Resolving translation-related conflicts in PRs.
- - Ensuring translation reflects current language usage and terminology.
- - Resolving translation-related GitHub issues and discussions.
+- The locale has an identified translation owner and code owner.
+- The ownership arrangement has been approved through the dev list process described below before merge.
+- The locale is added to the repository and UI configuration.
+- The locale follows the translation guidance in this document and the locale-specific guide, if one exists.
Review Comment:
Should we then also enforce that each new language creates a `.github/skills/airflow-translations/locales/<code>.md` file`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org