airflow-translations

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 extra keys (present in the locale but not in English), remove them:

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

After completing translations, run these checks:

Check completeness. The output should show 0 missing, 0 extra, and 0 TODOs:

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

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:

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

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:

admin.json, assets.json, browse.json, common.json, components.json, dag.json, dags.json, dashboard.json, hitl.json, tasks.json

---

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.

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