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-unsubscr...@airflow.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
