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 2025/06/02 09:53:15 UTC
[PR] i18 policy [airflow]
shahar1 opened a new pull request, #51292:
URL: https://github.com/apache/airflow/pull/51292
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!--
Thank you for contributing! 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 committers for the review!
In case of an existing issue, reference it using one of the following:
closes: #ISSUE
related: #ISSUE
How to write a good git commit message:
http://chris.beams.io/posts/git-commit/
-->
<!-- Please keep an empty line above the dashes. -->
---
**^ Add meaningful description above**
Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)** for more information.
In case of fundamental code changes, an Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals)) is needed.
In case of a new dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
In case of backwards incompatible changes please leave a note in a newsfragment file, named `{pr_number}.significant.rst` or `{issue_number}.significant.rst`, in [airflow-core/newsfragments](https://github.com/apache/airflow/tree/main/airflow-core/newsfragments).
--
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] Internationalization (i18n) policy [airflow]
Posted by "bugraoz93 (via GitHub)" <gi...@apache.org>.
bugraoz93 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124934495
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
Review Comment:
Suggestions look good. Falling back to English is a good option, but it could end up mixed support for a couple of releases if the language is inactive. Setting some boundaries is also a good option.
I think making this flexibility could already take another load from release managers. We should automate the exclusion in a way that releases managers shouldn't handle anything manual. We can easily understand if the language is active and supported or inactive with simple tricks. This should also be a newsfragment to include, which won't be supported in the next Nth release.
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "pierrejeambrun (via GitHub)" <gi...@apache.org>.
pierrejeambrun commented on PR #51292:
URL: https://github.com/apache/airflow/pull/51292#issuecomment-2941192144
> I had thought of a similar idea, but unfortunately the problem is that CODEOWNERS should be project maintainers (as @jscheffl previously mentioned).
I think notifying the sponsors is stil better than nothing. Becaus they are also responsible of having the translation up to date. (They add the final approval and merge)
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124620217
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
This is the most fundamental issue in the base of this policy - how do you even run such a vote, when most of the audience is not proficient in the target language? :)
--
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] Internationalization (i18n) policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2125737513
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,212 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Contributors responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+> [!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 translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated contributor responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation. Only Code owners have write permissions to the repository and can be listed in `.github/CODEOWNERS`.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+**Release manager** - according to the definition in the [Release Management Policy](../../../../../../dev/README_RELEASE_PROVIDERS.md#what-the-provider-distributions-are).
+
+**Dev. list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+**Inactive translation/code owner** — A translation owner/code owner is considered inactive if they meet either of the following criteria:
+
+- The translation under their responsibility has remained incomplete for at least two consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files in the `main` branch.
+- Where emphasised by capital letters, The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
Review Comment:
```suggestion
- Where emphasised by capital letters, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
```
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on PR #51292:
URL: https://github.com/apache/airflow/pull/51292#issuecomment-2941034009
> Maybe an easy way to help about translation owners being notified about required changes is simply to make every translation owners also code owners of the `en` translation folder.
Thanks for your suggestion!
I had thought of a similar idea, but unfortunately the problem is that CODEOWNERS should be project maintainers (as @jscheffl mentioned).
I added a section regarding what release managers should do. In short - they should only notify and declare a due date for completing missing translations. Incomplete translations shouldn't be a blocker.
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127909019
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
+- 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 a code owner who is also the translation owner can be done by a lazy consensus.
+- 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.
+
+### 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:
+ - The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for Taiwanese Chinese).
Review Comment:
```suggestion
- The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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).
```
I re-read the policy and fixed my comment. I also noticed communities that use IETF language tag (BCP 47) with ISO 639-1
--
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] i18n policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2122484816
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
Review Comment:
```suggestion
# Internationalization (i18n) Policy
```
not sure whether it's more clear this way 🤔
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
Review Comment:
should we add a link to `dev. list`?
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
+
+### 6.4. Relinquishing translation/code ownership
+
+- When a translation owner asks to relinquish their role, or becomes inactive, and there are no other translation owners available, the code owner should follow these steps:
+ - They should raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+ - They should post a thread in the dev. list that the translation owner relinquishes their role, and that they are looking for a replacement.
+ - If a replacement is found within a reasonable time, they should be approved according to the relevant steps in section 6.1 - and afterward the code owner should update the `.github/CODEOWNERS` file to reflect the new translation owner.
+ - Otherwise, the code owner should raise a vote in the dev. list for the removal if the translation from the codebase.
+- When a translation sponsor asks to relinquish their role, and there is at least one translation owner - they should ask in the dev. list for assigning another sponsor instead.
+
+
+## 7. Standards & guidelines
+
+- 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.
+- Translation of technical terminology should be consistent (for example: Dag, Task, Operator, etc.).
+- Language should be polite and neutral in tone.
+- Usage language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/) is prohibited.
+
+> [!NOTE]
+> In case that local conventions requires deviation from the following guidelines, exceptions may be requested via PR or the dev list.
+
+
Review Comment:
```suggestion
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
Review Comment:
Should we move this section above? I was confused when reading 4 without these context
--
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] i18n policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2123519676
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
+
+### 6.4. Relinquishing translation/code ownership
+
+- When a translation owner asks to relinquish their role, or becomes inactive, and there are no other translation owners available, the code owner should follow these steps:
+ - They should raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+ - They should post a thread in the dev. list that the translation owner relinquishes their role, and that they are looking for a replacement.
+ - If a replacement is found within a reasonable time, they should be approved according to the relevant steps in section 6.1 - and afterward the code owner should update the `.github/CODEOWNERS` file to reflect the new translation owner.
+ - Otherwise, the code owner should raise a vote in the dev. list for the removal if the translation from the codebase.
+- When a translation sponsor asks to relinquish their role, and there is at least one translation owner - they should ask in the dev. list for assigning another sponsor instead.
+
+
+## 7. Standards & guidelines
+
+- 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.
+- Translation of technical terminology should be consistent (for example: Dag, Task, Operator, etc.).
+- Language should be polite and neutral in tone.
+- Usage language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/) is prohibited.
+
+> [!NOTE]
+> In case that local conventions requires deviation from the following guidelines, exceptions may be requested via PR or the dev list.
+
+
+- Local conventions should be considered (e.g., date formats, number formatting, formal vs. informal tone, etc.)
+- Formatting, placeholders, and variable substitutions must be preserved.
+
+> [!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.
Review Comment:
1. What to do if they're not? Add/remove abbreviations? Take artistic freedom?
2. Should we require screenshots in PRs?
3. "languages with different word order than English" - there are too many languages that fit this description. I'm particularly worried about strings that mix multiple languages (and directions), e.g."ה-DAGים", which it is extremely easy to get wrong.
--
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] i18n policy [airflow]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2121386483
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,176 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet it not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files in the `main` branch.
+- Where emphasised by capital letters, The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following coniditions at any given time (except for transition times in section 6.4.):
Review Comment:
Fix typo: 'coniditions' should be 'conditions'.
```suggestion
Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,176 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet it not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files in the `main` branch.
+- Where emphasised by capital letters, The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following coniditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / repharsing terms
Review Comment:
Fix typo: 'repharsing' should be 'rephrasing'.
```suggestion
### 4.5. Adding / rephrasing terms
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,176 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet it not a translation owner.
Review Comment:
Grammar correction: change 'yet it not a translation owner' to 'yet is not a translation owner'.
```suggestion
**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
```
--
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] i18n policy [airflow]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2123070320
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
Review Comment:
I think we should also somehow involve release management here:
* what to do if we miss translations prior to release?
* who and when checks that? (we already have tool for that - see tooling section - it just needs to be run at some point in time.
* should release manager hold release before translations are complete or do we allow incomplete translations ?
I have no single answers or proposals to those but I guess we should at least think what to do and involve relase managers @kaxil and @ephraimbuddy (and others who might step in) so that they are not surprised they need to do something or that they do not even know they should do something.
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124422561
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
Review Comment:
Probably, but not necessarily - I made this distinction to allow non-committers to participate :)
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127842049
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
+- 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 a code owner who is also the translation owner can be done by a lazy consensus.
+- 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.
+
+### 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:
+ - The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for Taiwanese Chinese).
Review Comment:
```suggestion
- The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 639-1 or BCP 47 codes in lowercase (e.g., `zh-tw` for Taiwanese Mandarin).
```
I'm afraid I need to oppose using `ISO 3166-1`. We probably could use `ISO 639-1` with `IETF language tag (BCP 47)` instead
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127842049
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
+- 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 a code owner who is also the translation owner can be done by a lazy consensus.
+- 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.
+
+### 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:
+ - The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for Taiwanese Chinese).
Review Comment:
```suggestion
- The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 639-1 or BCP 47 codes in lowercase (e.g., `zh-tw` for Taiwanese Mandarin).
```
I need to oppose using `ISO 3166-1` and suggest using `ISO 639-1` with BCP 47 instead
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
Review Comment:
```suggestion
- When introducing a new locale, the thread should announce that on the dev list. (including a link to the PR)
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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.
Review Comment:
```suggestion
- They have basic skills of working with Git and GitHub, as well as modifying JSON translation files within their target language.
```
nit
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127829209
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
Review Comment:
```suggestion
- When introducing a new locale, the thread should announce that on the dev list. (including a link to the PR)
```
I was a bit confused at first glance 🤔 not sure whether it's better this way
--
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] i18n policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2123480140
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
Review Comment:
```suggestion
- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation:
```
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2132108982
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
Review Comment:
it should be "the same thread"
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124429677
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
Review Comment:
Nice to have IMO, and it's already being used in the CODEOWNERS file:
https://github.com/apache/airflow/blob/158dcb0169199a0c6758193b307c35bb97adab7a/.github/CODEOWNERS#L41
The idea is to encourage people to start contributing translations without having an "official" role,
so in future decisions they might be provided with it :)
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124478113
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
+
+### 6.4. Relinquishing translation/code ownership
+
+- When a translation owner asks to relinquish their role, or becomes inactive, and there are no other translation owners available, the code owner should follow these steps:
+ - They should raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+ - They should post a thread in the dev. list that the translation owner relinquishes their role, and that they are looking for a replacement.
+ - If a replacement is found within a reasonable time, they should be approved according to the relevant steps in section 6.1 - and afterward the code owner should update the `.github/CODEOWNERS` file to reflect the new translation owner.
+ - Otherwise, the code owner should raise a vote in the dev. list for the removal if the translation from the codebase.
+- When a translation sponsor asks to relinquish their role, and there is at least one translation owner - they should ask in the dev. list for assigning another sponsor instead.
+
+
+## 7. Standards & guidelines
+
+- 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.
+- Translation of technical terminology should be consistent (for example: Dag, Task, Operator, etc.).
+- Language should be polite and neutral in tone.
+- Usage language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/) is prohibited.
+
+> [!NOTE]
+> In case that local conventions requires deviation from the following guidelines, exceptions may be requested via PR or the dev list.
+
+
+- Local conventions should be considered (e.g., date formats, number formatting, formal vs. informal tone, etc.)
+- Formatting, placeholders, and variable substitutions must be preserved.
+
+> [!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.
Review Comment:
1. GitHub issue / PR for fixing it, like we do here the best (I'll add it) :)
2. I don't think that we should require - but reviewers might definitely ask contributors if they checked that the PR is according to the quality standards (we could even later create a PR template for translations).
3. That's correct, so both contributors and reviewers should be cautious about it. Moreover, I think that even in latin-scripted language we could have UI issues for templated strings.
--
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] Internationalization (i18n) policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2125757894
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
Review Comment:
Do we want to add internal hyperlinks to sections in the 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
Re: [PR] Internationalization (i18n) policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2125796907
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
Review Comment:
Re batching translation changes. I don't know what the current plan is but how about this:
- There will be a separate branch for i18n. Translation PRs will always target this branch. The branch may have unique CI configurations or approval requirements (as detailed in this document).
- To avoid adding to PR pressure, especially around releases, the i18n branch will be merged into main right before a release is cut. If permitted by Apache rules, i18n->main merges will occur at some fixed interval such as weekly or nightly.
- If the English source changes, this will be synced into the i18n branch via a PR that potentially includes notifying all translators. A small added benefit is it will make it easy for translators to see when their involvement might be needed, by inspecting the commit graph.
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127207268
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
Review Comment:
Shouldn't be harmful - it's common in other MD files.
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "jscheffl (via GitHub)" <gi...@apache.org>.
jscheffl commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2129936344
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
I do not have a strong opinion on this. Other is also okay. Just wanted to make it as much similar like other conflict resolutions in Apache guidelines. But I also assume conflicts are hopefully very rare and for example if @TJaniF and me can not agree on terms, then she just need to fork and create "Schwizerdeutsch" (de-CH) :-)
TLDR: I am also okay with @eladkal 's opinion.
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 merged PR #51292:
URL: https://github.com/apache/airflow/pull/51292
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124412383
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
Review Comment:
Here I actually meant GitHub issues :)
Anyway, the neutral tone is implied from the quality standards mentioned in the beginning
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124705032
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
Review Comment:
@potiuk I added a section about that in the version release docs, tl;dr:
1. We should do our best not to miss, but If we do - there's always the fall back to English.
2. Release managers should run the tool before releasing RC, and then sending a reminder urging code owners to ensure completion of translations before a due date.
3. IMO we should not hold, and allow incomplete translations up to X consecutive releases (I set `X=2`, but we could change this number if it's too strict). If the incomplete translation proceeds to X+1, it's an indication that the translation owners are inactive - and could be a valid reason for removing this translation like any other unused Airflow feature.
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "eladkal (via GitHub)" <gi...@apache.org>.
eladkal commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127256455
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
I am not sure if we should start mailing lists votes on language specific terminology. I don't think this is what the mailing list is for. A simple jusgment call from any PMC member should be sufficient on the PR itself (like any code change we have).
I don't think any code flavor "conflict" between 2 developer over a specific provider would have reach to a mailing list discussion. So in ny prespective it's kinda the same
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127842049
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
+- 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 a code owner who is also the translation owner can be done by a lazy consensus.
+- 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.
+
+### 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:
+ - The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for Taiwanese Chinese).
Review Comment:
```suggestion
- The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 639-1 or BCP 47 codes in lowercase (e.g., `zh-tw` for Taiwanese Mandarin).
```
I'm afraid I need to oppose using `ISO 3166-1` and suggest using `ISO 639-1` or `BCP 47` instead
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2128125356
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
Now, we need to solve a conflict by two PMC members 😅
I'm ok with both decisions - I don't expect that it would happen *too* often, but voting for a language aspect matter in th dev list feels indeed a bit odd.
Jens - what do you think?
--
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] Internationalization (i18n) policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2125742347
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,212 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Contributors responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+> [!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 translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated contributor responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation. Only Code owners have write permissions to the repository and can be listed in `.github/CODEOWNERS`.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+**Release manager** - according to the definition in the [Release Management Policy](../../../../../../dev/README_RELEASE_PROVIDERS.md#what-the-provider-distributions-are).
+
+**Dev. list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+**Inactive translation/code owner** — A translation owner/code owner is considered inactive if they meet either of the following criteria:
+
+- The translation under their responsibility has remained incomplete for at least two consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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.
+
+### 4.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related GitHub issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 4.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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
+
+Each supported translation, except for the default language, MUST meet one of the following conditions:
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one individual translation owner to enable peer reviews and provide coverage during individual absences.
+
+### 5.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes (as detailed in section 6.5), including technical terminology.
+- 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.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 5.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 5.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 5.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+- In busy times with many parallel UI changes it is acceptable to batch changes together, latest prior a release the differences SHOULD be cleared.
Review Comment:
```suggestion
- 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.
```
--
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] Internationalization (i18n) policy [airflow]
Posted by "bugraoz93 (via GitHub)" <gi...@apache.org>.
bugraoz93 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2125076714
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,212 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Contributors responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+> [!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 translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated contributor responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation. Only Code owners have write permissions to the repository and can be listed in `.github/CODEOWNERS`.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+**Release manager** - according to the definition in the [Release Management Policy](../../../../../../dev/README_RELEASE_PROVIDERS.md#what-the-provider-distributions-are).
+
+**Dev. list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+**Inactive translation/code owner** — A translation owner/code owner is considered inactive if they meet either of the following criteria:
+
+- The translation under their responsibility has remained incomplete for at least two consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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.
+
+### 4.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related GitHub issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 4.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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
+
+Each supported translation, except for the default language, MUST meet one of the following conditions:
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one individual translation owner to enable peer reviews and provide coverage during individual absences.
+
+### 5.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes (as detailed in section 6.5), including technical terminology.
+- 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.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 5.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 5.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 5.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+- In busy times with many parallel UI changes it is acceptable to batch changes together, latest prior a release the differences SHOULD be cleared.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 5.7. Approval and merging of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+- Before merging a translation-related PR, the translation should be checked for completeness using the provided tools (see section 8).
+
+> [!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).
+
+### 5.8. Version release
+
+- Requirements for release managers are defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation:
Review Comment:
Maybe we should also include sponsors to the thread and await approval from the sponsor in addition to binding votes rather than commenting in the Github?
Just and idea not a blocker
--
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] i18n policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2123503154
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
+
+### 6.4. Relinquishing translation/code ownership
+
+- When a translation owner asks to relinquish their role, or becomes inactive, and there are no other translation owners available, the code owner should follow these steps:
Review Comment:
Perhaps "inactive" should come with an exact definition, i.e. along the lines of "at least 3 months of the target language not being updated after changes to source strings were introduced".
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "bbovenzi (via GitHub)" <gi...@apache.org>.
bbovenzi commented on PR #51292:
URL: https://github.com/apache/airflow/pull/51292#issuecomment-2941416536
> > I had thought of a similar idea, but unfortunately the problem is that CODEOWNERS should be project maintainers (as @jscheffl previously mentioned).
>
> I think notifying the sponsors is still better than nothing. Becaus they are also responsible of having the translation up to date. (They add the final approval and merge)
+1 I worry less about exactly what CODEOWNERS mean but more on how to keep translations from slowing down or blocking the release cycle
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127842049
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
+- 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 a code owner who is also the translation owner can be done by a lazy consensus.
+- 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.
+
+### 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:
+ - The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for Taiwanese Chinese).
Review Comment:
```suggestion
- The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 639-1 or BCP 47 codes in lowercase (e.g., `zh-tw` for Taiwanese Mandarin).
```
I'm afraid I need to oppose using `ISO 3166-1` and suggest using `ISO 639-1` with `IETF language tag (BCP 47)` instead
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124239813
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
Review Comment:
I'll add a note about that in the scope
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124622898
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
+
+### 6.4. Relinquishing translation/code ownership
+
+- When a translation owner asks to relinquish their role, or becomes inactive, and there are no other translation owners available, the code owner should follow these steps:
Review Comment:
I'll add a definition for inactivity (tl;dr - two consecutive releases with incomplete translations, or inactivity in Airflow for more than 12 months)
--
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] i18n policy [airflow]
Posted by "jscheffl (via GitHub)" <gi...@apache.org>.
jscheffl commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2122088306
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
Review Comment:
Questioning myself: We make the rules here for the core UI... if we later start translating FAB UI or SimpleAuthManager... then we ajust the rule for these components managed in monorepo (potentially in future)?
(I would propose to start here and extend the definition if other compoentns e.g. airflowctl / FAB are translated if the rule is replicated... not to over-complicate here?
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
Review Comment:
```suggestion
**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation. Only Code owners have write permissions to the repository and can be listed in `.github/CODEOWNERS`.
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
Review Comment:
I'd propose to request more than one just as a fallback and vacation delegate
```suggestion
- Have at least one translation owner, with a translation sponsor assigned as a code owner.
It is welcomed and desired to have more than one individual translation owner to enable peer reviews and cover off-periods of individuals.
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
Review Comment:
I think can be done by anybody but need to be approved by a codeowner :-D
```suggestion
- 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)).
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
Review Comment:
Does it make sense to point to the article in Wikipedia with definitions?
```suggestion
**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes. See also ([Wikipedia: Internationalization and localization](https://en.wikipedia.org/wiki/Internationalization_and_localization))
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
Does this not rather need to follow the VOTING process like in debates about other technical / code questions?
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
Review Comment:
Repeat the policies here in regards of neutral tone?
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
Review Comment:
```suggestion
- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
- In busy times with many parallel UI changes it is acceptable to batch changes together, latest prior a release the differences must be cleared.
```
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
+
+### 6.4. Relinquishing translation/code ownership
+
+- When a translation owner asks to relinquish their role, or becomes inactive, and there are no other translation owners available, the code owner should follow these steps:
Review Comment:
What is a codeowner just goes passive and does not fulfill the role? Would it be acceptable that a different code owner also starts the process asking about status and maintenance?
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127204639
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,212 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Contributors responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+> [!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 translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated contributor responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation. Only Code owners have write permissions to the repository and can be listed in `.github/CODEOWNERS`.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+**Release manager** - according to the definition in the [Release Management Policy](../../../../../../dev/README_RELEASE_PROVIDERS.md#what-the-provider-distributions-are).
+
+**Dev. list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+**Inactive translation/code owner** — A translation owner/code owner is considered inactive if they meet either of the following criteria:
+
+- The translation under their responsibility has remained incomplete for at least two consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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.
+
+### 4.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related GitHub issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 4.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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
+
+Each supported translation, except for the default language, MUST meet one of the following conditions:
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one individual translation owner to enable peer reviews and provide coverage during individual absences.
+
+### 5.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes (as detailed in section 6.5), including technical terminology.
+- 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.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 5.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 5.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 5.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+- In busy times with many parallel UI changes it is acceptable to batch changes together, latest prior a release the differences SHOULD be cleared.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 5.7. Approval and merging of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+- Before merging a translation-related PR, the translation should be checked for completeness using the provided tools (see section 8).
+
+> [!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).
+
+### 5.8. Version release
+
+- Requirements for release managers are defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation:
Review Comment:
In case of sponsors, they are the designated code owners and should run the approval process.
I"ll clarify it in the next ammendment.
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127249475
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
I'm convinced, changed it to a decision by voting
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127842049
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
+- 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 a code owner who is also the translation owner can be done by a lazy consensus.
+- 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.
+
+### 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:
+ - The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for Taiwanese Chinese).
Review Comment:
```suggestion
- The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 639-1 or BCP 47 codes in lowercase (e.g., `zh-tw` for Taiwanese Mandarin).
```
I'm afraid I need to oppose using `ISO 3166-1` and suggest using `ISO 639-1` with BCP 47 instead
--
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] i18n policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2123490580
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
Review Comment:
Might be worth mentioning the acceptable standard for these entries (e.g. ISO 639-1 or 639-3). Perhaps it's worth transitioning the existing languages to the most recent standard, `639-3`, before it becomes too much work).
--
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] i18n policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2123475068
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
Review Comment:
How are translators notified about new strings being added? For example on Crowdin, whenever source strings are modified one can get an email. Is there going to be a similar notification mechanism here?
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2132120428
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
Restored the original phrasing, I'll notify about that in the vote
--
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] Internationalization (i18n) policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2125738109
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,212 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Contributors responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+> [!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 translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated contributor responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation. Only Code owners have write permissions to the repository and can be listed in `.github/CODEOWNERS`.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+**Release manager** - according to the definition in the [Release Management Policy](../../../../../../dev/README_RELEASE_PROVIDERS.md#what-the-provider-distributions-are).
+
+**Dev. list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+**Inactive translation/code owner** — A translation owner/code owner is considered inactive if they meet either of the following criteria:
+
+- The translation under their responsibility has remained incomplete for at least two consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
Review Comment:
```suggestion
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
```
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124432828
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
Review Comment:
We have Jarek's script, I'll add a reference for that
--
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] i18n policy [airflow]
Posted by "amoghrajesh (via GitHub)" <gi...@apache.org>.
amoghrajesh commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2122686100
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
Review Comment:
These will be same in most cases?
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
Review Comment:
Do we need this additional terminology
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
Review Comment:
demonstrate how? :D
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
Review Comment:
Agreed, start small, and build over it!
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
Review Comment:
Could we have a precommit that does it?
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
Review Comment:
Agreed, we can do this
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
Review Comment:
+1
--
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] i18n policy [airflow]
Posted by "Dev-iL (via GitHub)" <gi...@apache.org>.
Dev-iL commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2123504181
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
+
+### 6.4. Relinquishing translation/code ownership
+
+- When a translation owner asks to relinquish their role, or becomes inactive, and there are no other translation owners available, the code owner should follow these steps:
+ - They should raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+ - They should post a thread in the dev. list that the translation owner relinquishes their role, and that they are looking for a replacement.
+ - If a replacement is found within a reasonable time, they should be approved according to the relevant steps in section 6.1 - and afterward the code owner should update the `.github/CODEOWNERS` file to reflect the new translation owner.
+ - Otherwise, the code owner should raise a vote in the dev. list for the removal if the translation from the codebase.
Review Comment:
```suggestion
- Otherwise, the code owner should raise a vote in the dev. list for the removal of the translation from the codebase.
```
--
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] Internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124478113
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
+
+### 6.4. Relinquishing translation/code ownership
+
+- When a translation owner asks to relinquish their role, or becomes inactive, and there are no other translation owners available, the code owner should follow these steps:
+ - They should raise a PR for removal of the translation owner from the `.github/CODEOWNERS` file.
+ - They should post a thread in the dev. list that the translation owner relinquishes their role, and that they are looking for a replacement.
+ - If a replacement is found within a reasonable time, they should be approved according to the relevant steps in section 6.1 - and afterward the code owner should update the `.github/CODEOWNERS` file to reflect the new translation owner.
+ - Otherwise, the code owner should raise a vote in the dev. list for the removal if the translation from the codebase.
+- When a translation sponsor asks to relinquish their role, and there is at least one translation owner - they should ask in the dev. list for assigning another sponsor instead.
+
+
+## 7. Standards & guidelines
+
+- 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.
+- Translation of technical terminology should be consistent (for example: Dag, Task, Operator, etc.).
+- Language should be polite and neutral in tone.
+- Usage language that defies Apache Airflow's [code of conduct](http://airflow.apache.org/code-of-conduct/) is prohibited.
+
+> [!NOTE]
+> In case that local conventions requires deviation from the following guidelines, exceptions may be requested via PR or the dev list.
+
+
+- Local conventions should be considered (e.g., date formats, number formatting, formal vs. informal tone, etc.)
+- Formatting, placeholders, and variable substitutions must be preserved.
+
+> [!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.
Review Comment:
1. GitHub issue / PR for fixing it, like we do here the best (I'll add it) :)
2. I don't think that we should require that - but reviewers might definitely ask contributors if they checked that the PR is according to the quality standards (we could even later create a PR template for translations).
3. That's correct, so both contributors and reviewers should be cautious about it. Moreover, I think that even in latin-scripted language we could have UI issues for templated strings.
--
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] Internationalization (i18n) policy [airflow]
Posted by "jscheffl (via GitHub)" <gi...@apache.org>.
jscheffl commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2124956034
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
I hope there are no real "conflicts". Maybe just "opinons". But languages are usually not so strickt and multiple options are typically a matter of taste.
Anyway I assume PMC role is not needed but it should be rather a binding vote from all committers. Yeah and also if not proficient in the language. Will be the same but less people as PMC as well. Otherwise you could only roll a dice or create a fork of Airflow :-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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127237553
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
Review Comment:
@Dev-iL interesting idea, but let's maybe roll for 1-2 releases and then discuss if it's really needed - the effort for maintaining another branch (inc. related CI) at this point seems quite high IMO.
We could also think of a version management for langauge packages, but this requires a careful design as 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] Introduce internationalization (i18n) policy [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on PR #51292:
URL: https://github.com/apache/airflow/pull/51292#issuecomment-2949492204
> Set request changes just to make sure we have alignment on [#51292 (comment)](https://github.com/apache/airflow/pull/51292#discussion_r2127256455)
It has been resolved, could you please approve?
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "eladkal (via GitHub)" <gi...@apache.org>.
eladkal commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127256455
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
I am not sure if we should start mailing lists votes on language specific terminology. I don't think this is what the mailing list is for. A simple jusgment call from any PMC member should be sufficient on the PR itself (like any code change we have).
Similarly, I don't think any code flavor "conflict" between 2 developer over a specific provider would have reach to a mailing list discussion. So in nym prespective it's kinda the same
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,188 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# i18n Policy
+
+## 1. Purpose & 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.
+The scope of this policy is applied to:
+
+- Each supported language included in the `airflow-core/src/airflow/ui/src/i18n/locales` directory of the Apache Airflow project, or any suggested new translation.
+- Individuals responsible for maintaining these translations by any of the roles defined below.
+- Contributors who apply changes in the default language (English) that may affect translations.
+
+
+## 2. Definitions
+
+**i18n** - Internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
+
+**Supported translation** - A translation that has been officially accepted into the project, located in `airflow-core/src/airflow/ui/src/i18n/locales`.
+
+**Default language** - The language used by default, and as a fallback to all other languages (English).
+
+**Translation owner** - A designated individual responsible for the maintenance and quality for a supported translation.
+
+**Code owner** - An Apache Airflow committer designated in the `.github/CODEOWNERS` file for a supported translation.
+
+**Translation sponsor** - An Apache Airflow committer who supports a non-comitter translation owner (e.g., by merging Pull Requests on their behalf).
+
+**Engaged translator** - An Apache Airflow contributor who actively participates in the translation process, yet is not a translation owner.
+
+## 3. Wording/Phrasing
+
+- Unless specified explicitly, references to directories and files in the document refer to files 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 the RFC 2119.
+
+## 4. Requirements
+
+### 4.1. Translation ownership and code ownership
+
+Each supported translation, except for the default language, MUST meet one of the following conditions at any given time (except for transition times in section 6.4.):
+
+- Have at least one translation owner who is also a code owner.
+- Have at least one translation owner, with a translation sponsor assigned as a code owner.
+
+### 4.2. Approval of translation owners candidates
+
+- Translation owners candidates MUST declare and demonstrate a sufficient level of proficiency in the target language for translation purposes, including technical terminology.
+- 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 a Apache Airflow committer who will act as a translation sponsor.
+- Translation owners candidates MUST go through the approval process detailed in section 6.1.
+
+### 4.3. Approval of new translations
+
+To accept a new translation to the codebase, it MUST be approved through a review process discussed in section 6.2.
+
+### 4.4. Resolution of translation conflicts
+
+Translation conflicts MUST be resolved according to the procedures outlined in section 6.3.
+
+### 4.5. Adding / rephrasing terms
+
+- When new terms are added to the default language, all translation owners SHOULD create a follow-up PR to comply with the changes in their assigned language within a reasonable time.
+- When rephrasing terms in the default language, all translation owners SHOULD do the same as above, **if needed**.
+
+> [!NOTE]
+> Tooling for detecting missing translations is available (see Tools & Resources section below).
+
+### 4.6. Deprecating / refactoring terms
+
+When existing terms are deprecated or refactored (key renamed/relocated but value unchanged), **the contributor initiating the change is responsible for updating all language files, and not the translation/code owner**. Automation through Breeze tooling should be used when available.
+
+### 4.7. Approval of translation-related Pull Requests (PRs)
+
+- If the code owner is also a translation owner of the respective translation:
+ - Others' PRs should be approved and merged normally by them.
+ - Their own PRs should be approved and merged normally by another committer, preferably another code owner in their locale (if such exists).
+- Otherwise, if the code owner is sponsored:
+ - They should merge the translation-related PRs only after they are approved by the translation owner.
+- Other committers may review and approve translation-related PRs in any aspects, but they SHOULD NOT merge them without the approval of the translation owner and the consent of the code owner.
+
+## 5. Roles & responsibilities
+
+### 5.1. Translation owner
+
+- Translation owners are responsible for the following, in their assigned supported translation, according to established quality standards and procedures stated below:
+ - Ensuring translation remains up-to-date with source code changes in the default language.
+ - 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 issues and discussions.
+
+### 5.2. Code owner
+
+- Code owners are responsible for the following, in their assigned supported translation, 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 needed.
+ - Managing translation-related issues and discussions, when needed (e.g., closing issues).
+- Translations sponsors who function as code owners, are also responsible for ensuring that the translation owner is active and able to maintain the translation. If not, they should act according to section 6.4.
+
+### 5.3. Engaged translator
+
+- Engaged translators do not have any formal responsibilities, but they are encouraged to contribute to translations by:
+ - Suggesting improvements to existing translations.
+ - Reporting issues or inconsistencies in translations.
+ - Participating in discussions related to translations.
+ - Assisting translation owners with their tasks, when needed.
+ - Being 3rd party reviewers for translation-related PRs and conflicts, when needed.
+- They 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.
+
+## 6. Procedures
+
+### 6.1. Approval process of a translation owner
+
+- The designated code owner should post a thread in the dev. list to request for approval of the translation owner(s) for a supported translation.:
+ - Approvals of a translation owner who is also the code owner can be done by a lazy consensus.
+ - Approvals of translation owners who are non-committers require at least one binding vote of at least 1 PMC member, and no objections from committers/PMC.
+- Within the thread, the code owner should demonstrate that the translation owner is suitable for the role, according to the requirements in section 4.2.
+
+### 6.2. Approval process of a new translation
+
+The following steps outline the process for approving a new translation:
+> [!WARNING]
+> Before merging the PR, the committer should validate that files are in sync with the default language (English).
+
+- Creating a PR to add a new translation to the codebase ([see example](https://github.com/apache/airflow/pull/51258/files)), according to the standard and guidelines, which includes:
+ - The translation files in the `airflow-core/src/airflow/ui/src/i18n/locales/<LOCALE_CODE>` directory, where `<LOCALE_CODE>` is the code of the language (e.g., `fr` for French).
+ - 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)) (should be done by the code owner).
+ - Updating the `.github/CODEOWNERS` file to include the code owner(s).
+ > [!NOTE]
+ > When assigning a translation sponsor, there should be a comment in the `.github/CODEOWNERS` indicating who the translation owner(s) and the translation sponsor are.
+- Apply procedure 6.1. to approve the translation owner, while announcing the introduction of the new language (including a link to the PR).
+- Only after the steps above are completed, the PR for the new translation could be merged (by the requirements in section 4.7).
+
+### 6.3. Translation conflict resolution
+
+When a conflict arises in a translation-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 such as ChatGPT or Claude).
+- If the conflict is between code owners, a PMC member will be involved to resolve the conflict.
Review Comment:
I am not sure if we should start mailing lists votes on language specific terminology. I don't think this is what the mailing list is for. A simple jusgment call from any PMC member should be sufficient on the PR itself (like any code change we have).
Similarly, I don't think any code flavor "conflict" between 2 developer over a specific provider would have reach to a mailing list discussion. So in my prespective it's kinda the same
--
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] Introduce internationalization (i18n) policy [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #51292:
URL: https://github.com/apache/airflow/pull/51292#discussion_r2127842049
##########
airflow-core/src/airflow/ui/src/i18n/README.md:
##########
@@ -17,8 +17,221 @@
under the License.
-->
-Checking completeness of i18n files:
-------------------------------------
+# Internationalization (i18n) Policy
+
+## 1. Purpose & 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.
+
+### Scope
+
+This policy applies to:
+
+- Each supported locale included in `airflow-core/src/airflow/ui/src/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.
+
+> [!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/src/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.
+
+**Code owner** - Apache Airflow committer with write permissions, listed in `.github/CODEOWNERS`.
+
+**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).
+
+**Engaged translator** - Active contributor participating in translation without formal ownership.
+
+**Inactive translation/code owner** — A translation/code owner is considered inactive if they meet either of the following criteria:
+
+- The locale under their responsibility has remained incomplete for at least 2 consecutive releases.
+- They have not participated in the Apache Airflow project for more than 12 months.
+
+**Dev list** - The Apache Airflow development mailing list: dev@airflow.apache.org.
+
+## 3. Wording/Phrasing
+
+- 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.
+
+## 4. Roles & responsibilities
+
+### 4.1. Translation owner
+
+- 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.
+
+### 4.2. Code owner
+
+- 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 become inactive.
+
+### 4.3. Engaged translator
+
+- 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
+
+- 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.
+
+> [!NOTE]
+> It is welcomed and desired to have more than one translation owner to enable peer reviews and provide coverage during absences.
+
+### 5.2. Adding new locales
+
+To accept a new supported locale to the codebase, it MUST be approved through the process discussed in section 6.2.
+
+### 5.3. Translation owners 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, if the change in the intent or meaning affects the translation.
+- 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.
+
+> [!NOTE]
+> Tooling for detecting missing terms is available (see Tools & Resources section below).
+
+### 5.6. Deprecating / refactoring terms
+
+- When existing terms are deprecated or refactored in the default locale (key renamed/relocated but value unchanged), **the contributor initiating the change holds responsible for updating all relevant locale files, and not any of the locale's owners**. When such available, automation through Breeze tooling SHOULD be used.
+
+### 5.7. Merging of translation-related Pull Requests (PRs)
+
+- 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).
+
+> [!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).
+
+### 5.8. Version release
+
+- Release managers MUST follow the requirements for releasing changes in supported locales defined in the [Release Management Policy](../../../../../../dev/README_RELEASE_AIRFLOW.md).
+
+## 6. Procedures
+
+### 6.1. Approval of ownership candidates
+
+- The designated code owner, should post a thread to the dev list, requesting the approval of:
+ - Themselves as the code owner in the suggested locale. If they are a translation sponsor, they should indicate it as well.
+ - Other code owner(s) in the suggested locale, if applicable.
+ - The identity of the translation owner(s) in the suggested locale (which could be themselves as well)
+- When introducing a new locale, the thread should announce that (including a link to the PR)
+- 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 a code owner who is also the translation owner can be done by a lazy consensus.
+- 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.
+
+### 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:
+ - The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 follows ISO 3166-1 or UN M.49 codes in lowercase (e.g., `zh-tw` for Taiwanese Chinese).
Review Comment:
```suggestion
- The locale files (translated according to the guidelines) in the `airflow-core/src/airflow/ui/src/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 639-1 or BCP 47 codes in lowercase (e.g., `zh-tw` for Taiwanese Mandarin).
```
I'm afraid I need to oppose using `ISO 3166-1`. We probably could use `ISO 639-1` with `IETF language tag (BCP 47)` instead
--
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