glaterza opened a new pull request, #45181: URL: https://github.com/apache/superset/pull/45181
### SUMMARY This PR adds a Translation Guide to the developer docs. It covers what to translate and how terminology decisions get made. The mechanics stay in [Contributing Translations](https://superset.apache.org/developer-docs/contributing/howtos#contributing-translations). Translators of each language find the same problems on their own. One example: Spanish, Romanian and Serbian each render "dashboard" and Explore's "control panel" with the same words. No single catalog entry looks wrong, so per-string review cannot catch the collision. The page has six short sections: - When to keep the English term: product names, strings that a program reads, and terms that the user also sees in their own tools. It also covers placeholders and the `#. do-not-translate` marker. - Terms that mean two things, with the Spanish, Romanian and Serbian example and a search that finds it. - Rules for the whole catalog: formal or informal address, nouns for people, spelling and punctuation, and plural forms. The examples include Russian *ё* or *е*, and a final full stop on one-sentence messages. - Deciding on a term: count the forms, and native speakers decide in the pull request. - Recording a decision in the pull request that makes it, with a `fix(i18n-<lang>)` title. - Context for a single string: a pointer to `i18n:` comments, which #44397 added. The howto now links back to the guide. The PR also corrects one placement rule in the howto, and it adds one more case. In #44397, the howto said that pybabel drops a note above a wrapped Python call. A test shows that pybabel drops the note only when nothing, or only a comment, follows the string. A comma or a keyword argument after the string keeps the note. Also, with two calls on one line, only the first call gets the note. I put a note above each of the 1,005 `_(` and `__(` calls in `superset/`, without migrations. For 126 of them, pybabel dropped the note. The page is the "prose on the docs site" part of [discussion #43562](https://github.com/apache/superset/discussions/43562). @rusackas supported that split. It keeps to choices a person makes; a tool checks the rest. ### BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF Before: master has no Translation Guide page. After: the page renders on the local docs dev server. Its sidebar entry sits under Contributing, between *Development How-tos* and *Release Process*. <!-- DROP 01-guide-page-and-sidebar.jpg HERE --> The guide's last link opens the howto heading `adding-context-for-translators`, which lists the note placement rules: <!-- DROP 02-howto-adding-context-anchor.jpg HERE --> ### TESTING INSTRUCTIONS ```bash cd docs && yarn install && yarn start # open http://localhost:3000/developer-docs/contributing/translation-guide ``` Check three things on the rendered page: 1. The sidebar lists "Translation Guide" under Contributing, after "Development How-tos". 2. "Contributing Translations" opens `howtos#contributing-translations`. 3. "Adding context for translators" opens `howtos#adding-context-for-translators`. `developer_docs` uses `routeBasePath: 'developer-docs'`. The `/docs/*` redirects map to user docs, so `/docs/contributing/translation-guide` is a different route. The dev server returns HTTP 200 for an unknown route and renders "Page Not Found", so check the page itself. To check the collision example, compare `Dashboard` with the "control panel" message in the `es`, `ro`, `sr` and `sr_Latn` catalogs. ### 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) -- 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]
