Proposal: a translation guide, with shared principles and per-language conventions

[glaterza]

Why this Discussion exists

This continues a thread from Slack #translations. I posted an RFC there about four contested Spanish terms, and @sfirke suggested the conversation belongs here, both to make it findable and because the problem is not specific to Spanish.

Before writing this post I measured all 29 translation catalogs with polib, counting actual entries, and read through the terminology debates in past PRs. Every language is hitting the same traps on its own. Several languages have already made good decisions that are recorded nowhere. And in PR #40431, two German translators asked whether a glossary exists. The answer, on the record: "I don't think there is a glossary or something like that which can be followed."

So this proposes we create one. Most of the work is writing down what maintainers and translators already do.

The evidence

1. The same collision exists in five languages, independently.

In many languages the most natural translation of "dashboard" is some calque of "control panel". That rendering then collides with Explore's actual control panel (3 msgids), and one term ends up carrying two concepts. It has happened five separate times:

Language	Term serving both concepts	Dashboard entries using it
Spanish	panel de control	131
Romanian	panou de control	138
Serbian (both scripts)	контролна табла / kontrolna tabla	~140
Arabic	لوحة التحكم	67

There are partial overlaps in pt, pt_BR, tr, lv and sl as well. Korean has a different collision: 데이터베이스 covers both "database" and "dataset", including on the bare Dataset msgid. Polish shows the opposite failure. No collision there, but "dashboard" fragments five ways (pulpit, pulpit nawigacyjny, panel kontrolny, plain dashboard, tablica) across 188 strings.

Nobody did anything wrong. The trap is structural. A one-line shared principle, "check your dashboard rendering against your control panel rendering", would have prevented all five collisions.

2. Jargon fed to machine translation produces a recognizable mistranslation genre.

"Slug" is currently Slak (the snail) in Dutch, سبيكة (a metal ingot) in Arabic, Kopfzeile (a header) in German, and Logotyp (a logo) in Polish. Italian translates "Host" as Ospite, a guest. Russian renders "Backend" as Драйвер. These are exactly the words a do-not-translate list catches. We already have the machine-side infrastructure for that in superset/translations/do-not-translate.txt. Nothing equivalent exists for human-language terminology.

Heavily fuzzy catalogs also carry a second defect class: machine suggestions pasted in from unrelated strings entirely. Polish has "Create Tag" rendered as "Utwórz zestaw danych", which means "create dataset", and "Charts per row" as "Wiersz nagłówka", a header row. A glossary will not fix that class. A native review checklist will.

3. Good decisions already exist

Mining past PRs surfaced settled, well argued conventions that live only in closed review threads:

• German (chore(i18n): update German (de) translation #40431): dataset → Datensatz, with Record moved to "Eintrag" to resolve the ambiguity that started the debate. Also fix(i18n): update German security menu translations #41587: keep the gender-inclusive "Benutzer*innen" form, decided by native lazy consensus.
• French (chore(i18n): update french po file to match latest pot file version #40635, feat(i18n): adopt French translation improvements from #41688 #41752): dataset → jeu de données, email → courriel, metric → mesure, tag → étiquette. Several of these were decided by counting the catalog's dominant convention (104 vs 20, 74 vs 20), not by taste.
• pt_PT (fix(i18n): review and complete Portuguese (pt_PT) translation catalog #42137): Guardar rather than Salvar, utilizadores rather than usuários, and dashboard stays English.
• Russian (fix(i18n): improved Russian translation #28572): chart → Диаграмма, not График, which names a line plot specifically. "Superset" is never transliterated.

The next contributor in each language will re-argue all of this from zero unless it gets written down.

What other projects do

The mature projects converge on the same two-layer shape: one language-agnostic guide for principles and process, plus per-locale glossaries owned by each language community. WordPress runs per-locale glossaries with editor approval and a rule that changes happen "only by consensus and based on argued reasoning". Mozilla keeps a general style guide plus one guide per locale. GitLab keeps central meta-rules plus a glossary in Crowdin.

Two ideas are worth stealing outright.

GitLab keeps all git commands untranslated in every language, with the stated reason "to maintain consistency between GitLab and the git client". That is the principled version of the keep-English rule.

WordPress records the reasoning next to each glossary term. Their Spanish team documented why "dashboard" became Escritorio, rejecting tablero, cuadro de mando and salpicadero along the way. Whatever you think of the word they landed on, the next translator can read why instead of reopening the debate.

Those projects keep the live glossary inside their translation platform (Crowdin, GlotPress and the like). Superset translates via PRs, so in-repo markdown is our natural equivalent, and do-not-translate.txt is existing precedent for keeping a terminology registry inside superset/translations/.

Proposal

superset/translations/
├── TRANSLATING.md          # shared, language-agnostic (new)
├── do-not-translate.txt    # exists, machine/proper-noun registry
└── glossary/
    ├── de.md               # per-language conventions (new, seeded from
    ├── es.md               #   the PR decisions above + catalog data)
    ├── fr.md
    └── ...

TRANSLATING.md would carry the shared principles. Deliberately few:

1. Translate for fluency by default. Keep English only when a term falls into one of these categories:
   (a) proper nouns and product names,
   (b) code-level tokens, like SQL keywords and placeholders,
   (c) external-ecosystem vocabulary. These are terms your users also see in tools outside Superset (Host, Slug, Backend, a Snowflake or Databricks Warehouse), where translating breaks the connection to what their database tooling shows them. This last category is the GitLab git-commands rule, generalized. The catalogs already vote this way: most languages keep or transliterate slug, host and backend, while "database" is translated natively in 27 of 29 and is every catalog's most internally consistent term.
2. One term per concept, and one concept per term. The dashboard and control panel collision above is the worked example.
3. Decisions are made by native-speaker lazy consensus, on counted evidence, and the reasoning is recorded. That just codifies how the French and German threads above were actually resolved.

glossary/<lang>.md files hold each language's settled terms, each with a one-line why, plus a list of known bad renderings so that review, human or automated, can flag them mechanically.

One packaging detail to be aware of: MANIFEST.in includes everything under superset/translations/, so glossary markdown placed there would ship inside the released PyPI package. Nothing reads it at runtime and the size cost is a few kilobytes, the same situation as the existing do-not-translate.txt.
If that bothers anyone, a one-line recursive-exclude keeps the glossary in the repo but out of releases. Flagging it so the choice is deliberate.

Open questions

1. Does superset/translations/ plus a glossary/ directory sound like the right home?
2. Are the four shared principles above the right set? Anything missing or overreaching?
3. Should the initial per-language files be seeded from PR history and catalog measurements, or should each language team start from scratch? I am happy to draft es, and can prepare de, fr, pt_PT and ru drafts from the decisions above for native speakers to review. A native-speaker review of the Polish findings is underway as a pilot of exactly this process, results to follow in this thread.
4. For languages whose catalogs are essentially unreviewed machine output (Korean, Finnish and Thai are around 90% fuzzy), does a glossary help, or is a native review pass the prerequisite?

Appendix: what a glossary entry could look like (Spanish, illustrative)

Two draft entries, shown for format only. The Spanish specifics are still under discussion with es speakers.

control panel → panel de configuración
Why: panel de control currently serves two concepts, dashboard (131 entries) and Explore's control panel (3 entries). Renaming the 3-entry side resolves the collision at minimal cost. Panel de configuración has zero existing uses and does not collide with Settings, which is Ajustes. (This is a terminology choice, not a defect fix. Panel de control is a correct translation of "control panel". The clash comes from dashboard also taking the term.)

Host → «Host» (keep English)
Why: external-ecosystem vocabulary. A DBA sees "Host" in their own connection tooling. Set in guillemets per the RAE's rule for unadapted foreign words in Spanish text. The marking applies in help-text prose, not in tight UI labels.

And the forbidden side of an entry, from shipped catalogs: "Slug" must never become Slak (Dutch, the snail), سبيكة (Arabic, a metal ingot) or Logotyp (Polish, a logo). All three are live today.

[rusackas]

In general, I appreciate this kind of thinking/effort SO much, and much of it sounds like the right move.

My worry is that the glossaries won't be maintained, as we've already seen to be the case by the translations themselves... I worry it'll play second fiddle to an already-undermaintained feature.

Anything that improves the automation of translations (always in flux) would be amazing.

I wonder if the .pot file can include some structured comments that get passed through to the .po files or at least be leveraged by the AI translation backfill script, so more of the strings are "contextualized" with context, and we avoid at least these term ambiguity problems you pointed out (I always talk about "turkey" being a bird, a country, and an insult, but yours are more practical).

I.e. if there was a .pot "way" to add comments like:

#: src/foo.js:42
# context: "slug refers to the unique identifier in a URL" 
msgid "slug"
msgstr "XXXXXX"

Then that might provide enough context for AI (or humans) to know what to drop there.

As for policies, I agree, standards are needed. I'd be supportive of a docs site entry covering these. Things like tu/usted framing in spanish, or how we standardize on gendered languages (presumably preferring gender-neutral). Until there is a rule, nobody's breaking the rule.