glaterza commented on code in PR #44397:
URL: https://github.com/apache/superset/pull/44397#discussion_r4125330232
##########
docs/developer_docs/contributing/howtos.md:
##########
@@ -323,6 +323,46 @@ pybabel extract -F babel.cfg -o
superset/translations/messages.pot -k lazy_gette
npm run build-translation
```
+### Adding context for translators
+
+A translatable string arrives in a catalog with no surrounding code, so a term
+that is unambiguous in context can be guessed wrong in isolation. Shipped
+examples include `Slug` rendered as the animal, `Host` as a guest, and
`Backend`
+as a driver.
+
+To attach context, put a comment tagged `i18n:` immediately above the string:
+
+```python
+# i18n: the short identifier in a dashboard's URL, not the animal
+"slug": _("Slug"),
+```
+
+```tsx
+// i18n: the database engine behind a connection (PostgreSQL, MySQL), not
+// a server tier or a driver
+Header: t('Backend'),
+```
+
+`babel_update.sh` extracts these with `--add-comments=i18n:`, so they land on
the
+entry in `messages.pot` as `#. i18n: ...` and `pybabel update` propagates them
Review Comment:
Fixed in the latest push. The "Extracting new strings for translation"
section now points at `./scripts/translations/babel_update.sh` instead of a
bare `pybabel extract`. It also says why: the script passes the frontend
keywords, extracts `i18n:` comments, and stamps do-not-translate markers. The
old command was already broken before this PR: it referenced a `babel.cfg` at
the repo root, which does not exist, and had no frontend keywords.
##########
scripts/translations/babel_update.sh:
##########
@@ -40,11 +40,18 @@ cat <<'EOF'> "$LICENSE_TMP"
EOF
cd $ROOT_DIR
+# --add-comments=i18n:: carry translator context from the source into the
+# catalogs. A comment tagged `i18n:` immediately above a translatable string is
+# extracted as a `#. i18n: ...` comment on that entry, and (like the
+# do-not-translate marker below) propagates into every language catalog on the
+# `pybabel update` further down. Only `i18n:`-tagged comments are extracted, so
+# ordinary code comments near a string are not published to translators.
pybabel extract \
-F superset/translations/babel.cfg \
-o superset/translations/messages.pot \
--no-location \
--sort-output \
+ --add-comments=i18n: \
Review Comment:
Fixed in the latest push. I added `--add-comments=i18n:` to `EXTRACT_FLAGS`
in `check_pot_drift.py`. The "kept in sync" comment is now enforced:
`test_extract_flags_match_babel_update_sh` parses the script's `pybabel
extract` call and compares it with `EXTRACT_FLAGS`. It fails without the fix.
The drift check still compares only msgids, so the comments themselves aren't
diffed; the flag parity is what keeps the two invocations from drifting apart.
--
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]
