GitHub user glaterza created a discussion: Proposal: a translation guide, with shared principles and per-language conventions
## 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](https://github.com/apache/superset/pull/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 (#40431): dataset → Datensatz, with Record moved to "Eintrag" to resolve the ambiguity that started the debate. Also #41587: keep the gender-inclusive "Benutzer\*innen" form, decided by native lazy consensus. - French (#40635, #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 (#42137): Guardar rather than Salvar, utilizadores rather than usuários, and dashboard stays English. - Russian (#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. GitHub link: https://github.com/apache/superset/discussions/43562 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
