Re: [D] Proposal: a translation guide, with shared principles and per-language conventions [superset]

["glaterza (via GitHub)" <gi...@apache.org>]

GitHub user glaterza added a comment to the discussion: Proposal: a translation guide, with shared principles and per-language conventions

Thanks both.

**On the maintenance worry.** @rusackas is right. A glossary that only humans read will go stale, and nothing breaks when it does, so nobody notices. So I would narrow the proposal: the parts a tool can check (keep-English terms, known-bad renderings) go next to the catalogs, and the rest — register, gendered forms, how a decision gets made — goes on the docs site as short prose. If nothing reads it, don't write it.

**On the .pot comments.** What you described already exists here:

- `do-not-translate.txt` lists 27 terms.
- `apply_do_not_translate.py` stamps `#. do-not-translate` on each one in `messages.pot`.
- `pybabel update` copies those comments into every catalog. All 30 carry them today, including the Tamil catalog that was added after I did the original measurement. Nobody had to touch the registry for that to happen, which is worth weighing against the maintenance worry.
- `backfill_po.py` reads the marker and skips those strings.

So the path from `.pot` to `.po` to the AI backfill is already built and in use.

The missing piece is your example: a note written by the developer next to the string. `babel_update.sh` runs `pybabel extract` without `--add-comments`, so comments in source never reach the `.pot`. Babel 2.17, our pin, supports it. One flag plus a convention:

```python
# i18n: unique identifier in a URL, not the animal
label = _("slug")
```

That becomes `#. i18n: ...` in the `.pot`, reaches all 30 catalogs on the next update, and is available to translators and to the backfill prompt.

Small PR, worth doing on its own whether or not the glossary happens. I will open it if there is no objection.

One warning: use `#.` comments, not `msgctxt`. `msgctxt` changes the message key, no catalog uses it, and there is no `pgettext` support in the backend or in `@superset-ui/core`, so it would mean new runtime work. Comments need none.

What per-string notes do not fix: they clarify one string at a time. The problem I measured is across strings — `panel de control` meaning both "dashboard" and "control panel". You cannot see that from any single entry. That needs a short per-language term list. Different problems, both worth solving.

**@sfirke on the count:** three, not four. Miscount, sorry. If there should be a fourth, I would use @rusackas's point: each language states its register and its stance on gendered forms once, in its own file. Those get re-argued in every PR.

On a pointer inside each translation file: agreed, and a script should write it, the same way the do-not-translate markers are written, so it cannot drift across 30 files.

**Polish pilot:** it has not started yet. I have a native Polish speaker lined up and expect it to begin after this week. I will report the results here.

**Next step:** I would start with the `--add-comments` change. It is useful by itself and it proves the whole path works. The glossary format can be argued out afterwards, with the pipeline already running.

GitHub link: https://github.com/apache/superset/discussions/43562#discussioncomment-18386451

----
This is an automatically sent email for notifications@superset.apache.org.
To unsubscribe, please send an email to: notifications-unsubscribe@superset.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org