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 bc023b0a42. 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, normalizes the template, 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 bc023b0a42. 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`. The test failed before 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]
