This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new f0a7828197c refine skill md for airflow translation (#63060)
f0a7828197c is described below
commit f0a7828197ca5c25b40387c07e9f1eb02a70ffd9
Author: Kevin Yang <[email protected]>
AuthorDate: Sat Mar 7 16:12:45 2026 -0500
refine skill md for airflow translation (#63060)
---
.github/skills/airflow-translations/SKILL.md | 343 +++++++++++++++++----------
1 file changed, 213 insertions(+), 130 deletions(-)
diff --git a/.github/skills/airflow-translations/SKILL.md
b/.github/skills/airflow-translations/SKILL.md
index 24fc4aa4d47..d5467f31e22 100644
--- a/.github/skills/airflow-translations/SKILL.md
+++ b/.github/skills/airflow-translations/SKILL.md
@@ -1,10 +1,10 @@
---
name: airflow-translations
description: >
- Translate, review, and maintain Apache Airflow i18n locale strings in JSON
- translation files. Use when working with internationalization, localization,
- or translation tasks in airflow-core/src/airflow/ui/public/i18n/locales/.
- Covers Airflow terminology conventions and translation guidelines.
+ Add or update translations for the Apache Airflow UI.
+ Guides through setting up locales, scaffolding translation files, translating
+ with locale-specific guidelines, and validating results. Use when working
with
+ i18n tasks in airflow-core/src/airflow/ui/public/i18n/locales/.
license: Apache-2.0
---
<!-- SPDX-License-Identifier: Apache-2.0
@@ -12,154 +12,237 @@ license: Apache-2.0
# Airflow Translations
-## Locale-Specific Guidelines
+## Determining the Task
-Before translating, you **must** read the locale-specific guideline file for
-the target language. Locale files are located at `locales/<locale-name>.md`
-relative to this skill directory.
+Translation work falls into one of two categories depending on whether the
+target locale already exists. Check if a directory for the locale exists under
+`airflow-core/src/airflow/ui/public/i18n/locales/<locale>/`. If it does, skip
+ahead to **Updating an Existing Translation**. If not, start with **Adding a
Translation** below.
-Match the translation task to the correct locale file using the table below:
+---
-| Locale Code | Language | Guideline File |
-| ----------- | ----------------------- | ------------------------------- |
-| `ar` | Arabic | [locales/ar.md](locales/ar.md) |
-| `ca` | Catalan | [locales/ca.md](locales/ca.md) |
-| `de` | German | [locales/de.md](locales/de.md) |
-| `el` | Greek | [locales/el.md](locales/el.md) |
-| `es` | Spanish | [locales/es.md](locales/es.md) |
-| `fr` | French | [locales/fr.md](locales/fr.md) |
-| `he` | Hebrew | [locales/he.md](locales/he.md) |
-| `hi` | Hindi | [locales/hi.md](locales/hi.md) |
-| `hu` | Hungarian | [locales/hu.md](locales/hu.md) |
-| `it` | Italian | [locales/it.md](locales/it.md) |
-| `ja` | Japanese | [locales/ja.md](locales/ja.md) |
-| `ko` | Korean | [locales/ko.md](locales/ko.md) |
-| `nl` | Dutch | [locales/nl.md](locales/nl.md) |
-| `pl` | Polish | [locales/pl.md](locales/pl.md) |
-| `pt` | Portuguese | [locales/pt.md](locales/pt.md) |
-| `th` | Thai | [locales/th.md](locales/th.md) |
-| `tr` | Turkish | [locales/tr.md](locales/tr.md) |
-| `zh-CN` | Simplified Chinese | [locales/zh-CN.md](locales/zh-CN.md)
|
-| `zh-TW` | Traditional Chinese | [locales/zh-TW.md](locales/zh-TW.md)
|
+## Adding a Translation
-If the target locale file does not yet exist, follow only the global rules in
this document.
-When a locale-specific guideline conflicts with a global rule, the
**locale-specific
-guideline takes precedence**.
+When adding a translation, some configuration files need to be updated before
translation work can begin.
-## Translation File Structure
+### Setting up the locale
-All translation files are JSON files located at:
+First, create the locale directory:
```
-airflow-core/src/airflow/ui/public/i18n/locales/<locale-name>/
+mkdir -p airflow-core/src/airflow/ui/public/i18n/locales/<locale>/
```
-Each locale directory contains namespace JSON files that mirror the English
-locale (`en/`). The English locale is the **default locale** and the primary
-source for all translations. The current namespace files are:
+Then update the following configuration files, keeping the existing
alphabetical
+ordering in each file:
-<!-- START namespace-files, please keep comment here to allow auto update -->
-`admin.json`, `assets.json`, `browse.json`, `common.json`, `components.json`,
`dag.json`, `dags.json`, `dashboard.json`, `hitl.json`, `tasks.json`
-<!-- END namespace-files, please keep comment here to allow auto update -->
+**`airflow-core/src/airflow/ui/src/i18n/config.ts`**: add the locale to the
+`supportedLanguages` array:
+
+```ts
+{ code: "<locale>", name: "<native name>" },
+```
+
+**`dev/breeze/src/airflow_breeze/commands/ui_commands.py`**: add the plural
+suffixes for the language to the `PLURAL_SUFFIXES` dict. Check the i18next
+plural rules for the language at <https://jsfiddle.net/6bpxsgd4> to determine
+which suffixes are needed:
+
+```
+"<locale>": ["<suffixes>"],
+```
+
+**`.github/boring-cyborg.yml`**: under `labelPRBasedOnFilePath`, add:
+
+```yaml
+translation:<locale>:
+ - airflow-core/src/airflow/ui/public/i18n/locales/<locale>/*
+```
+
+### Scaffolding the translation files
+
+Once the configuration is in place, run the breeze command to copy every
+English namespace file into the new locale directory. This populates each key
+with a `TODO: translate:` stub:
+
+```bash
+breeze ui check-translation-completeness --language <locale> --add-missing
+```
+
+The generated files will look like this:
+
+```json
+{
+ "allRuns": "TODO: translate: All Runs",
+ "blockingDeps": {
+ "dependency": "TODO: translate: Dependency",
+ "reason": "TODO: translate: Reason"
+ }
+}
+```
+
+### Translating
+
+With the scaffolded files in place, read the locale-specific guideline for the
+target language (see the table under **Locale-Specific Guidelines** below). If
+one exists, it contains the glossary, tone rules, and formatting conventions
+that must be followed. If no locale-specific guideline exists yet, follow the
+translation rules described later in this document.
+
+Replace every `TODO: translate: <English terminology>` entry, including the
prefix,
+with the translated string.
+
+After all entries are translated, continue to **Validation** below.
+
+---
+
+## Updating an Existing Translation
+
+When a locale already exists and you need to fill translation gaps, revise
+existing translations, or remove stale keys, start by reading the
+locale-specific guideline for the language (see the table under
+**Locale-Specific Guidelines** below). This establishes the glossary and
+formatting rules to follow.
+
+Next, read the locale's existing JSON files under
+`airflow-core/src/airflow/ui/public/i18n/locales/<locale>/` to learn the
+terminology already in use. Consistency with established translations is
+critical. If a term has been translated a certain way, reuse that exact
+translation.
+
+Then check the current state of completeness:
+
+```bash
+breeze ui check-translation-completeness --language <locale>
+```
+
+If there are **missing** keys, scaffold them with `TODO: translate:` stubs:
+
+```bash
+breeze ui check-translation-completeness --language <locale> --add-missing
+```
+
+If there are **extra** keys (present in the locale but not in English), remove
+them:
+
+```bash
+breeze ui check-translation-completeness --language <locale> --remove-extra
+```
+
+Now translate the `TODO: translate:` entries following the locale-specific
+guideline, then continue to **Validation** below.
+
+---
+
+## Validation
-## Translation Principles
+After completing translations, run these checks:
+
+Check completeness. The output should show 0 missing, 0 extra, and 0 TODOs:
+
+```bash
+breeze ui check-translation-completeness --language <locale>
+```
+
+Run pre-commit hooks to fix formatting, licenses, and linting issues:
+
+```bash
+prek run --from-ref main --hook-stage pre-commit
+```
+
+---
-1. **Concise and clear** — Translations are used in UI elements (buttons,
- labels, tooltips). Keep them short and suitable for constrained UI space.
-2. **Consistent** — Always use the same translated term for the same English
- term. Refer to the glossary in your locale file.
-3. **Accurate** — Maintain the original meaning and intent.
-4. **Neutral tone** — Language should be polite and neutral.
-5. **Local conventions** — Respect date formats, number formatting, and
- formal/informal tone as appropriate for the locale.
+## General Translation Rules
-## Do-Not-Translate Terms
+The following rules apply globally. If the locale-specific guideline for a
+language states differently, follow the locale-specific guideline.
-The following terms should remain in English by default. Locale-specific
-guidelines may override individual entries where established conventions exist:
+### Terms Kept in English
-| Term | Reason
|
-| ------------------------ |
------------------------------------------------------------- |
-| `Airflow` | Product name
|
-| `Dag` / `Dags` | Airflow convention; always use `Dag`, never `DAG`
|
-| `XCom` / `XComs` | Airflow cross-communication mechanism name
|
-| `Provider` / `Providers` | Airflow extension package name
|
-| `REST API` | Standard technical term
|
-| `JSON` | Standard technical format name
|
-| `ID` | Universal abbreviation
|
-| `PID` | Unix process identifier
|
-| `UTC` | Time standard
|
-| `Schema` | Database term (keep unless locale has established
convention) |
+The terms below should remain in English by default. Locale-specific guidelines
+may override individual entries where an established local convention exists:
-## Variable and Placeholder Handling
+| Term | Reason |
+| ------------------------ | -------------------------------------------- |
+| `Airflow` | Product name |
+| `Dag` / `Dags` | Airflow convention; always `Dag`, never `DAG`|
+| `XCom` / `XComs` | Airflow cross-communication mechanism name |
+| `Provider` / `Providers` | Airflow extension package name |
+| `REST API` | Standard technical term |
+| `JSON` | Standard technical format name |
+| `ID` | Universal abbreviation |
+| `PID` | Unix process identifier |
+| `UTC` | Time standard |
+| `Schema` | Database term |
-Translation strings use the `{{variable}}` interpolation syntax (i18next
-format):
+### Variables and Placeholders
-- **Never translate** variable names inside `{{...}}`.
-- **Never remove** any `{{variable}}` placeholders.
-- **Reorder** placeholders as needed to match natural word order.
-- **Preserve** exact variable casing (e.g., `{{dagDisplayName}}`).
+Translation strings use `{{variable}}` interpolation (i18next format).
+Never translate or remove variable names inside `{{…}}`. Placeholders may be
+reordered as needed for natural word order, but the exact variable casing must
+be preserved (e.g., `{{dagDisplayName}}`).
-## Plural Forms
+### Plural Forms
Airflow uses i18next plural suffixes (`_one`, `_other`, and optionally `_zero`,
-`_two`, `_few`, `_many`). Provide translations for **all** plural suffixes
-relevant to the language you provide translation for.
+`_two`, `_few`, `_many`). Provide translations for all plural suffixes that the
+language requires — the locale-specific guideline specifies which ones. If no
+locale guideline exists, check the i18next plural rules at
+<https://jsfiddle.net/6bpxsgd4> and provide at minimum `_one` and `_other`.
-## Hotkeys
+### Hotkeys
Hotkey values (e.g., `"hotkey": "e"`) are literal key bindings and should
-**not** be translated unless the locale-specific guideline specifies otherwise.
-
-## Translation Workflow
-
-1. **Read** the locale-specific guideline (`locales/<locale-name>.md`).
-2. **Identify** missing translations — use `--add-missing` to generate stubs
- prefixed with `TODO: translate`:
-
- ```bash
- breeze ui check-translation-completeness --language <locale-name>
--add-missing
- ```
-
-3. **Translate** the `TODO: translate` entries using this guide and the locale
- glossary.
-4. **Remove** extra keys not present in the English source:
-
- ```bash
- breeze ui check-translation-completeness --language <locale-name>
--remove-extra
- ```
-
-5. **Validate** completeness:
-
- ```bash
- breeze ui check-translation-completeness --language <locale-name>
- ```
-
-## Common Airflow Terms
-
-The following terms appear frequently in the English source files. Each locale
-glossary should define consistent translations for them. The **Context** column
-disambiguates terms that may have different meanings outside of Airflow:
-
-| English Term | Context |
-| -------------------- | ---------------------------------------- |
-| Task | Unit of work in a Dag |
-| Task Instance | Single run of a Task |
-| Task Group | Logical grouping of Tasks |
-| Dag Run | Single execution of a Dag |
-| Operator | Type/class that defines a Task |
-| Trigger | Event or mechanism that starts a run |
-| Trigger Rule | Condition that determines Task execution |
-| Triggerer | Airflow component that handles triggers |
-| Schedule / Scheduler | Timing configuration / Airflow component |
-| Backfill | Retroactive execution of Dag Runs |
-| Asset | Data dependency tracked by Airflow |
-| Asset Event | Notification that an Asset was updated |
-| Connection | External system credentials |
-| Variable | Key-value configuration store |
-| Pool | Resource constraint mechanism |
-| Plugin | Extensibility mechanism |
-| Executor | Component that runs Tasks |
-| Queue | Execution queue for Tasks |
-| Audit Log | Record of system events |
+**not** be translated unless the locale-specific guideline says otherwise.
+
+---
+
+## Translation File Structure
+
+All translation files are JSON files located at:
+
+```
+airflow-core/src/airflow/ui/public/i18n/locales/<locale-name>/
+```
+
+Each locale directory contains namespace JSON files that mirror the English
+locale (`en/`). The English locale is the **default locale** and the primary
+source for all translations. The current namespace files are:
+
+<!-- START namespace-files, please keep comment here to allow auto update -->
+`admin.json`, `assets.json`, `browse.json`, `common.json`, `components.json`,
`dag.json`, `dags.json`, `dashboard.json`, `hitl.json`, `tasks.json`
+<!-- END namespace-files, please keep comment here to allow auto update -->
+
+---
+
+## Locale-Specific Guidelines
+
+Before translating, read the locale-specific guideline file for the target
+language. These contain glossaries, tone rules, and formatting conventions
+tailored to each language. If a locale-specific guideline states differently
+from a global rule in this document, follow the locale-specific guideline.
+
+| Locale Code | Language | Guideline File |
+| ----------- | ----------------------- | ------------------------------- |
+| `ar` | Arabic | [locales/ar.md](locales/ar.md) |
+| `ca` | Catalan | [locales/ca.md](locales/ca.md) |
+| `de` | German | [locales/de.md](locales/de.md) |
+| `el` | Greek | [locales/el.md](locales/el.md) |
+| `es` | Spanish | [locales/es.md](locales/es.md) |
+| `fr` | French | [locales/fr.md](locales/fr.md) |
+| `he` | Hebrew | [locales/he.md](locales/he.md) |
+| `hi` | Hindi | [locales/hi.md](locales/hi.md) |
+| `hu` | Hungarian | [locales/hu.md](locales/hu.md) |
+| `it` | Italian | [locales/it.md](locales/it.md) |
+| `ja` | Japanese | [locales/ja.md](locales/ja.md) |
+| `ko` | Korean | [locales/ko.md](locales/ko.md) |
+| `nl` | Dutch | [locales/nl.md](locales/nl.md) |
+| `pl` | Polish | [locales/pl.md](locales/pl.md) |
+| `pt` | Portuguese | [locales/pt.md](locales/pt.md) |
+| `th` | Thai | [locales/th.md](locales/th.md) |
+| `tr` | Turkish | [locales/tr.md](locales/tr.md) |
+| `zh-CN` | Simplified Chinese | [locales/zh-CN.md](locales/zh-CN.md)
|
+| `zh-TW` | Traditional Chinese | [locales/zh-TW.md](locales/zh-TW.md)
|
+
+If the target locale file does not yet exist, follow only the global rules in
+this document.
