9.1 KiB
name, description, license
| name | description | license |
|---|---|---|
| airflow-translations | 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/. | Apache-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 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:
| 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}}).
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.
| 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 |
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.