From ec7e5dc8b698a68987f8355e810ddc1412ef8914 Mon Sep 17 00:00:00 2001 From: Alex Vandiver Date: Wed, 25 Jun 2025 18:16:34 +0000 Subject: [PATCH] docs: Update for switch from Transifex to Weblate. --- docs/overview/architecture-overview.md | 2 +- docs/subsystems/release-checklist.md | 19 ++- docs/translating/internationalization.md | 51 +------ docs/translating/translating.md | 141 +++++++++--------- help/include/translation-project-info.md | 4 +- .../comparison_table_integrated.html | 2 +- templates/corporate/for/business.html | 2 +- templates/corporate/for/education.html | 2 +- templates/corporate/for/events.html | 2 +- templates/corporate/for/open-source.html | 2 +- templates/corporate/for/research.html | 2 +- tools/linter_lib/exclude.py | 4 - 12 files changed, 95 insertions(+), 138 deletions(-) diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index 0bbbe0b307..c45843c1da 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -28,7 +28,7 @@ adapter](https://github.com/zulip/hubot-zulip); integrations with [Trello](https://github.com/zulip/trello-to-zulip); and [many more](https://github.com/zulip/). -We use [Transifex](https://explore.transifex.com/zulip/zulip/) to do +We use [Weblate](https://hosted.weblate.org/projects/zulip/) to do translations. In this overview, we'll mainly discuss the core Zulip server and web diff --git a/docs/subsystems/release-checklist.md b/docs/subsystems/release-checklist.md index 6e763c2b10..a581d46afd 100644 --- a/docs/subsystems/release-checklist.md +++ b/docs/subsystems/release-checklist.md @@ -12,11 +12,9 @@ preparing a new release. - Upgrade all puppet dependencies in `puppet/deps.yaml` - Upgrade all puppet-installed dependencies (e.g., Smokescreen, go, etc) in `puppet/zulip/manifests/common.pp` - - [Upload strings to - Transifex](../translating/internationalization.md#translation-process) - using `push-translations`. Post a Transifex - [announcement](https://app.transifex.com/zulip/communication/?q=project%3Azulip) - notifying translators that we're approaching a release. + - [Post a message to + Weblate](https://hosted.weblate.org/projects/zulip/#announcement) + inviting translators to translate new strings. - Merge draft updates to the [changelog](../overview/changelog.md) with changes since the last release. While doing so, take notes on things that might need follow-up work or documentation before we @@ -30,8 +28,8 @@ preparing a new release. ### Final release preparation - Update the Paper blog post draft with any new commits. -- Download updated translation strings from Transifex and commit - them. Use the `--branch 6.x` parameter for maintenance releases. +- Merge updated translations from Weblate (using the appropriate + branch for the release). - Use `build-release-tarball` to generate a pre-release tarball. - Test the new tarball extensively, both new install and upgrade from last release, on Ubuntu 22.04. @@ -103,9 +101,10 @@ preparing a new release. - Add the new release to `.github/ISSUE_TEMPLATE/2_bug_report.md`. - Consider removing a few old releases from the issue template and ReadTheDocs; we keep about two years of back-versions. - - Update Transifex to add the new `4.x` style release branch - resources and archive the previous release branch's resources with - the "Translations can't translate this resource" setting. + - Update Weblate to add a component on the release branch for + Django; then add a parallel Frontend component by using "Duplicate + this component" on the Django release branch component. + - In Weblate, remove the previous stable components. - Add a new CI production upgrade target: - Build a docker image: `cd tools/ci && docker build . -f Dockerfile.prod --build-arg=BASE_IMAGE=zulip/ci:bookworm --build-arg=VERSION=7.0 --tag=zulip/ci:bookworm-7.0 && docker push zulip/ci:bookworm-7.0` - Add a new line to the `production_upgrade` matrix in diff --git a/docs/translating/internationalization.md b/docs/translating/internationalization.md index b8e03d1423..da73372d7d 100644 --- a/docs/translating/internationalization.md +++ b/docs/translating/internationalization.md @@ -329,20 +329,13 @@ The end-to-end tooling process for translations in Zulip is as follows. - It will not override the value of a singular key if that value contains a translated text. -3. Those resource files are uploaded to Transifex by a maintainer using the - `./tools/i18n/push-translations` command (which invokes a Transifex - API tool, `tx push`, internally). +3. Those resource files, when committed, are automatically scanned by + Weblate. -4. Translators translate the strings in the Transifex UI. (In theory, - it's possible to translate locally and then do `tx push`, but - because our workflow is to sync translation data from Transifex to - Zulip, making changes to translations in Zulip risks having the - changes blown away by a data sync, so that's only a viable model - for a language that has no translations yet). +4. Translators translate the strings in the Weblate UI. -5. The translations are downloaded back into the codebase by a - maintainer, using `tools/i18n/sync-translations` (which invokes the - Transifex API tool, `tx pull`, internally). +5. Weblate makes the translations into a Git commit, which then can be + merged into the codebase by a maintainer. If you're interested, you may also want to check out the [translators' workflow](translating.md#translators-workflow), just so you have a @@ -353,36 +346,7 @@ sense of how everything fits together. All the translation magic happens through resource files, which hold the translated text. Server resource files are located at `locale//LC_MESSAGES/django.po`, while web app resource -files are located at `locale//translations.json` (and -mobile at `mobile.json`). - -These files are uploaded to [Transifex][], where they can be translated. - -## Working with Transifex - -### Transifex config - -The config file that maps the resources from Zulip to Transifex is -located at `.tx/config`. - -### Transifex CLI setup - -In order to be able to run `tx pull` (and `tx push` as well, if you're a -maintainer), you have to specify your Transifex API Token, [generated in -Transifex's web interface][transifex-api-token], in a config file located at -`~/.transifexrc`. - -You can find details on how to set it up [here][transifexrc], but it should -look similar to this (with your credentials): - -```ini -[https://www.transifex.com] -rest_hostname = https://rest.api.transifex.com -token = 1/abcdefg... -``` - -This basically identifies you as a Transifex user, so you can access your -organizations from the command line. +files are located at `locale//translations.json`. ## Additional resources @@ -397,7 +361,4 @@ their style guidelines. [formatjs]: https://formatjs.github.io/ [icu messageformat]: https://formatjs.github.io/docs/core-concepts/icu-syntax#plural-format [helpers]: https://handlebarsjs.com/guide/block-helpers.html -[transifex]: https://www.transifex.com -[transifex-api-token]: https://app.transifex.com/user/settings/api/ -[transifexrc]: https://docs.transifex.com/client/client-configuration#transifexrc [html-templates]: ../subsystems/html-css.md#html-templates diff --git a/docs/translating/translating.md b/docs/translating/translating.md index f638b045ef..fdbcb4b949 100644 --- a/docs/translating/translating.md +++ b/docs/translating/translating.md @@ -25,45 +25,52 @@ Zulip: That channel is also the right place for any questions, updates on your progress, reporting problematic strings, etc. -1. Sign up for [Transifex](https://www.transifex.com) and ask to join the [Zulip - project on Transifex](https://explore.transifex.com/zulip/zulip/), requesting access - to any languages that you'd like to contribute to (or add new ones). +1. [Sign up for Weblate](https://hosted.weblate.org/accounts/register/). :::{note} Unless you plan to contribute country-specific translations, do not - select a country-specific language in the **Languages** menu when you sign - up. E.g., use **English (United Kingdom)** if you plan to translate Zulip - into UK English, but select **Russian** rather than **Russian (Russia)** for - general Russian translations. + select a country-specific language in the **Languages** list when + you sign up. E.g., use **English (United Kingdom) (en_GB)** if you + plan to translate Zulip into UK English, but select **Spanish + (es)** rather than **Spanish (Colombia) (es_CO)** for general + Spanish translations. ::: -1. Wait for a maintainer to approve your Transifex access; this - usually takes less than a day. You should then be able to access - Zulip's dashboard in Transifex. +1. Navigate to the [Zulip project on Weblate](https://hosted.weblate.org/projects/zulip/). -1. Translate the strings for your language in Transifex. Zulip has - several resource files: +1. Choose the language you'd like to translate into; your preferred + languages should be at the top. - - `mobile.json` is for the iOS/Android mobile apps. - - `desktop.json` is for the parts of the Zulip desktop apps that - are not shared with the Zulip web app. - - `django.po` and `translations.json` have strings for the next - major release of the Zulip server and web app (which is what we - run on chat.zulip.org and Zulip Cloud). - - The variants of `django.po` and `translations.json` with names - starting with a version, like `5-x--`, are strings for Zulip's +1. Optionally, use the "Components" tab at the top to translate only + part of the project. Zulip has several different components, split + up by where they are used: + + - `Flutter` is used for the mobile app. + - `Desktop` is for the parts of the Zulip desktop apps that are not + shared with the Zulip web app. This is a fairly small number of + strings. + - `Django` and `Frontend` have strings for the next major release + of the Zulip server and web app (which is what we run on + chat.zulip.org and Zulip Cloud). + - The variants of `Django` and `Frontend` with names + ending with a version, like `(10.x)`, are strings for Zulip's current [stable release series](../overview/release-lifecycle.md). - Transifex is smart about only asking you to translate a string once - even if it appears in multiple resources. The `5-x--` type variants + Weblate is smart about only asking you to translate a string once + even if it appears in multiple resources. The `(10.x)` type variants allow translators to get a language to 100% translated for the current release. +1. Click the "Translate" button to begin translating. Refer to + [Weblate's + documentation](https://docs.weblate.org/en/latest/user/translating.html#translating) + for how to translate each string. + 1. If possible, test your translations (details below). -1. Ask in Zulip for a maintainer to sync the strings from Transifex, - merge them to `main`, and deploy the update to chat.zulip.org so - you can verify them in action there. +1. Ask in Zulip for a maintainer to merge the strings from Weblate, + and deploy the update to chat.zulip.org so you can verify them in + action there. Some useful tips for your translating journey: @@ -72,42 +79,36 @@ Some useful tips for your translating journey: doesn't exist one, write one as you go; they're easiest to write as you go along and will help any future translators a lot. +- Use, and update, the [Weblate + glossary](https://hosted.weblate.org/projects/zulip/glossary/) for + your language. This will help by providing consistent, inline + translation references for terms (e.g., "channel") which are used + repeatedly throughout the application. + - Don't translate variables or code (usually preceded by a `%`, inside HTML tags `<...>`, or enclosed in braces like `{variable}`); just keep them verbatim. -- Be consistent with translations; so make sure you are using the same translation - for the same word/phrase across all files (unless the context is different). - -- When context is unclear, you may find [GitHub - search](https://github.com/search?q=org%3Azulip+%22alert+word+already+exists%22&type=code) - helpful for finding the code using a given string (ignore `.po` and - `.json` matches, and note the search box is semi-invisible in the - upper-left corner of the page), or looking at the "Occurrences" - section in the Transifex UI, browsing to the file on - [GitHub](https://github.com/zulip/zulip/), and then searching for - the string with `Ctrl+F` in your browser. +- When context is unclear, you may find it helpful to follow the + "Source string location" link in the right sidebar of the Weblate + UI. - When in doubt, ask for context in [#translation](https://chat.zulip.org/#narrow/channel/58-translation) in the [Zulip development community server](https://zulip.com/development-community/). -- If there are multiple possible translations for a term, search for it in - the _Concordance_ tool (the button with a magnet in the top right corner). - - It will show if anyone translated that term before, so we can achieve good - consistency with all the translations, no matter who makes them. - - Pay attention to capital letters and punctuation. Details make the - difference! + difference! Weblate will catch, and warn about, some cases of + mismatched punctuation. -- Take advantage of the hotkeys the Transifex Web Editor provides, such as - `Tab` for saving and going to the next string. +- Take advantage of Weblate's [key + bindings](https://docs.weblate.org/en/latest/user/translating.html#keyboard-shortcuts) + for efficiency. -- While one should definitely prioritize translating - `translations.json`, since the most prominent user-facing strings - are there, API error messages in `django.po` are presented to users, - so a full translation should include them. +- While one should definitely prioritize translating the `Frontend` + and `Flutter` components, since the most prominent user-facing + strings are there, API error messages in `Django` are presented to + users, so a full translation should include them. ### Testing translations @@ -116,12 +117,17 @@ This section assumes you have a if setting one up is a problem for you, ask in chat.zulip.org and we can usually just deploy the latest translations there. -- First, download the updated resource files from Transifex using the - `tools/i18n/sync-translations` command (it will require some [initial - setup](internationalization.md#transifex-cli-setup)). This - command will download the resource files from Transifex and replace - your local resource files with them, and then compile them. You can - now test your translation work in the Zulip UI. +1. Add the Weblate remote to your Git repository: + + ```shell + git remote add weblate https://hosted.weblate.org/git/zulip/django/ + ``` + +1. Merge the changes into your local repository: + + ```shell + git cherry-pick weblate/main ^upstream/main + ``` There are a few ways to see your translations in the Zulip UI: @@ -162,23 +168,14 @@ There are a few ways to see your translations in the Zulip UI: ### Machine translation -Transifex has [built-in machine translation -capabilities](https://help.transifex.com/en/articles/6271130-setting-up-machine-translation). +Weblate has [built-in machine translation +capabilities](https://docs.weblate.org/en/latest/admin/machine.html). If machine translation is enabled for your language, you can generate one by -clicking the **lightning** symbol above the translation box. +clicking the **Automatic suggestions** tab below the translation box. -![Transifex machine translation button](../images/transifex-machine-translation-button.png) - -There are a few things to keep in mind if you choose to make use of machine -translation: - -- We expect human-quality translations for Zulip. While machine translation can - be a helpful aid, please be sure to review all machine translated strings. - -- We are using machine translation in HTML mode, which has a known bug that - causes special characters to be rendered as their HTML encodings. For example, - a `'` will be converted to ` '`. Please be sure to fix this when reviewing - translations. +Bear in mind that we expect human-quality translations for +Zulip. While machine translation can be a helpful aid, please be sure +to review all machine translated strings. ### Translation style guides @@ -197,6 +194,10 @@ translators can understand and preserve those decisions: - [Russian](russian.md) - [Spanish](spanish.md) +We encourage this information to also be placed in [Weblate's +glossary](https://hosted.weblate.org/projects/zulip/glossary/), which +will help provide inline suggestions when translating. + Some translated languages don't have these, but we highly encourage translators for new languages (or those updating a language) write a style guide as they work, since it's easy to take notes as you diff --git a/help/include/translation-project-info.md b/help/include/translation-project-info.md index edde9367ae..45f5c46fba 100644 --- a/help/include/translation-project-info.md +++ b/help/include/translation-project-info.md @@ -1,9 +1,9 @@ Zulip has been translated or partially translated into dozens of languages by Zulip's amazing community of volunteer translators. -You can see which languages Zulip supports [on Transifex][transifex-zulip]. +You can see which languages Zulip supports [on Weblate][weblate-zulip]. If you'd like to help by contributing as a translator, see the [Zulip translation guidelines][translating-zulip] to get started. -[transifex-zulip]: https://explore.transifex.com/zulip/zulip/ +[weblate-zulip]: https://hosted.weblate.org/projects/zulip/ [translating-zulip]: https://zulip.readthedocs.io/en/stable/translating/translating.html diff --git a/templates/corporate/comparison_table_integrated.html b/templates/corporate/comparison_table_integrated.html index 3f08fc98f5..cba37ff8f6 100644 --- a/templates/corporate/comparison_table_integrated.html +++ b/templates/corporate/comparison_table_integrated.html @@ -202,7 +202,7 @@ - Localized in more than 20 languages + Localized in more than 20 languages diff --git a/templates/corporate/for/business.html b/templates/corporate/for/business.html index 834579b93c..3ac14af347 100644 --- a/templates/corporate/for/business.html +++ b/templates/corporate/for/business.html @@ -537,7 +537,7 @@ when you need their attention. -
  • Use Zulip in your language of choice, with translations into 23 languages.
    • +
  • Use Zulip in your language of choice, with translations into 23 languages.
    • diff --git a/templates/corporate/for/education.html b/templates/corporate/for/education.html index 10c521c9ec..d3480933a6 100644 --- a/templates/corporate/for/education.html +++ b/templates/corporate/for/education.html @@ -254,7 +254,7 @@
    Mention users, groups of users or everyone when you need their attention.
  • -
    Use Zulip in your language of choice, with translations into 23 languages.
    +
    Use Zulip in your language of choice, with translations into 23 languages.
  • Zulip works reliably for organizations with thousands of users online at once.
    diff --git a/templates/corporate/for/events.html b/templates/corporate/for/events.html index 007bb1651e..e71853f629 100644 --- a/templates/corporate/for/events.html +++ b/templates/corporate/for/events.html @@ -134,7 +134,7 @@
    Make a video call with the click of a button.
  • -
    Use Zulip in your language of choice, with translations into 23 languages.
    +
    Use Zulip in your language of choice, with translations into 23 languages.
    • diff --git a/templates/corporate/for/open-source.html b/templates/corporate/for/open-source.html index 8bc1f89d0b..704e0d27d2 100644 --- a/templates/corporate/for/open-source.html +++ b/templates/corporate/for/open-source.html @@ -613,7 +613,7 @@
  • Use Zulip in your language of choice, with translations into - 23 languages. + 23 languages.
  • diff --git a/templates/corporate/for/research.html b/templates/corporate/for/research.html index 28856502a4..35b686d684 100644 --- a/templates/corporate/for/research.html +++ b/templates/corporate/for/research.html @@ -374,7 +374,7 @@ when you need their attention.
    • -
  • Use Zulip in your language of choice, with translations into 23 languages.
    • +
  • Use Zulip in your language of choice, with translations into 23 languages.
    • diff --git a/tools/linter_lib/exclude.py b/tools/linter_lib/exclude.py index 0a3af23c6c..54463e87ed 100644 --- a/tools/linter_lib/exclude.py +++ b/tools/linter_lib/exclude.py @@ -2,10 +2,6 @@ EXCLUDED_FILES = [ # Third-party code that doesn't match our style "web/third", - # Transifex syncs translation.json files without trailing - # newlines; there's nothing other than trailing newlines we'd be - # checking for in these anyway. - "locale", ] PUPPET_CHECK_RULES_TO_EXCLUDE = [