glaterza opened a new pull request, #44397:
URL: https://github.com/apache/superset/pull/44397
### SUMMARY
A translatable string reaches a catalog with no surrounding code, so a term
that is unambiguous at
the call site can be guessed wrong in isolation. This is not hypothetical —
each of these is in a
catalog on master today:
| msgid | locale | current translation | reads as |
|---|---|---|---|
| `Slug` | `nl` | `Slak` | the animal (a snail/slug) |
| `Slug` | `de` | `Kopfzeile` | "header line" |
| `Host` | `it` | `Ospite` | "guest" |
| `Backend` | `ru` | `Драйвер` | "Driver" |
| `Backend` | `fr` | `Serveur` | "server", not the engine |
Russian renders `Slug` correctly as `Читаемый URL` ("readable URL"), which
is the point: the failure
is per-language and per-string, so it cannot be fixed once centrally — the
context has to travel
with the string.
This passes `--add-comments=i18n:` to `pybabel extract`, so a comment tagged
`i18n:` immediately
above a translatable string is published to translators as a `#. i18n: ...`
extracted comment on
that entry:
```python
# i18n: the short identifier in a dashboard's URL, not the animal
"slug": _("Slug"),
```
```
#. i18n: the short identifier in a dashboard's URL, not the animal
msgid "Slug"
msgstr ""
```
Extracted comments propagate from `messages.pot` into every language catalog
on `pybabel update` —
the same mechanism the existing `#. do-not-translate` marker uses — so the
context is visible to
human translators and to the AI backfill without any new machinery.
Only `i18n:`-tagged comments are extracted, so ordinary code comments near a
string are not
published to translators.
Seeds the convention on four terms with known bad renderings in the catalogs
on master, and
documents it under Contributing Translations.
Verified by running `babel_update.sh` end to end: the four comments are
extracted from source
(Python, TS and TSX, including one in JSX attribute position), land on the
correct `msgid`s, and
propagate to **all 30 language catalogs** (exactly 4 per catalog). Untagged
comments next to a
translatable string are not extracted, and `msgfmt --check-format` passes.
The `do-not-translate` markers are unaffected by this change. Note that a
full run against current
source stamps **24** of them, not the 27 in the committed template:
`pivoted_xlsx`, `step-after` and
`step-before` are listed in `do-not-translate.txt` but are no longer
extractable from source. That
is pre-existing template drift, independent of this PR.
This implements a suggestion from @rusackas in
[discussion #43562](https://github.com/apache/superset/discussions/43562).
**Related, but not a prerequisite.** #44395 repairs the `msgcat`
normalization step in the same
script. The two are independent and can land in either order: they change
different parts of
`babel_update.sh`, and the four `#. i18n:` comments here apply to the
template exactly as committed.
If both land, whichever merges second wants `babel_update.sh` re-run to
regenerate the template —
mechanical tool output, not a hand edit.
A docs PR adding a Translation Guide follows once this one lands; it links a
heading this PR adds to
`howtos.md`, so that one genuinely does depend on this.
### BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
Not applicable — no UI change. `#. i18n:` comments are build-time metadata
with zero runtime
effect; the docs half adds a prose section under Contributing Translations,
readable in the diff.
### TESTING INSTRUCTIONS
```bash
./scripts/translations/babel_update.sh
# the comments are on the .pot entries:
grep -A2 '^#\. i18n:' superset/translations/messages.pot
# and reached every catalog (expect 30):
grep -l '^#\. i18n:' superset/translations/*/LC_MESSAGES/messages.po | wc -l
```
Note that `babel_update.sh` re-extracts from source, so it also pulls in
pre-existing template
drift — 428 strings present in source but missing from the committed
template, measured at
`35768da1fd`. None of that is from this PR; the four `#. i18n:` comments are
its only contribution
to the template.
Add a comment tagged `i18n:` above any `_()` or `t()` call, re-run, and
confirm it appears on that
entry — and that an untagged comment above another string does not.
### ADDITIONAL INFORMATION
- [ ] Has associated issue:
- [ ] Required feature flags:
- [ ] Changes UI
- [ ] Includes DB Migration (follow approval process in
[SIP-59](https://github.com/apache/superset/issues/13351))
- [ ] Migration is atomic, supports rollback & is backwards-compatible
- [ ] Confirm DB migration upgrade and downgrade tested
- [ ] Runtime estimates and downtime expectations provided
- [ ] Introduces new feature or API
- [ ] Removes existing feature or API
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
