airflow-translations

<!-- SPDX-License-Identifier: Apache-2.0 https://www.apache.org/licenses/LICENSE-2.0 -->

Airflow Translations

Determining the Task

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.

---

Adding a Translation

When adding a translation, some configuration files need to be updated before translation work can begin.

Setting up the locale

First, create the locale directory:

mkdir -p airflow-core/src/airflow/ui/public/i18n/locales/<locale>/

Then update the following configuration files, keeping the existing alphabetical ordering in each file:

airflow-core/src/airflow/ui/src/i18n/config.ts: add the locale to the supportedLanguages array:

{ 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:

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:

breeze ui check-translation-completeness --language <locale> --add-missing

The generated files will look like this:

{
  "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:

breeze ui check-translation-completeness --language <locale>

If there are missing keys, scaffold them with TODO: translate: stubs:

breeze ui check-translation-completeness --language <locale> --add-missing

If there are unused keys — keys that are not required, meaning they are absent from the English locale or are plural suffixes this language does not need — remove them:

breeze ui check-translation-completeness --language <locale> --remove-unused

Now translate the TODO: translate: entries following the locale-specific guideline, then continue to Validation below.

---

Validation

After completing translations, run these checks:

Check completeness. The output table should show 0 missing, 0 TODOs, 0 unused, and 100% coverage:

breeze ui check-translation-completeness --language <locale>

For machine-readable validation, add --json and check the language's totals instead — stdout carries only the JSON document:

breeze ui check-translation-completeness --language <locale> --json

Run pre-commit hooks to fix formatting, licenses, and linting issues:

prek run --from-ref main --hook-stage pre-commit

---

General Translation Rules

The following rules apply globally. If the locale-specific guideline for a language states differently, follow the locale-specific guideline.

Terms Kept in English

The terms below should remain in English by default. Locale-specific guidelines may override individual entries where an established local convention exists:

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

Variables and Placeholders

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}}).

Counters use the i18next number formatter so they get the locale's digit grouping (e.g., {{count, number}}, {{total, number}}). Keep the , number suffix exactly as it appears in the English string.

Plural Forms

Airflow uses i18next plural suffixes (_one, _other, and optionally _zero, _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

Hotkey values (e.g., "hotkey": "e") are literal key bindings and should 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
ca	Catalan	locales/ca.md
de	German	locales/de.md
el	Greek	locales/el.md
es	Spanish	locales/es.md
fr	French	locales/fr.md
he	Hebrew	locales/he.md
hi	Hindi	locales/hi.md
hu	Hungarian	locales/hu.md
it	Italian	locales/it.md
ja	Japanese	locales/ja.md
ko	Korean	locales/ko.md
nl	Dutch	locales/nl.md
pl	Polish	locales/pl.md
pt	Portuguese	locales/pt.md
ru	Russian	locales/ru.md
th	Thai	locales/th.md
tr	Turkish	locales/tr.md
zh-CN	Simplified Chinese	locales/zh-CN.md
zh-TW	Traditional Chinese	locales/zh-TW.md

If the target locale file does not yet exist, follow only the global rules in this document.