snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

docs/translating/translating.md

@@ -0,0 +1,232 @@
+# Translation guidelines
+
+Zulip has full support for Unicode (and partial support for RTL
+languages), so you can use your preferred language everywhere in
+Zulip.
+
+Additionally, the Zulip UI is translated into more than a dozen major
+languages, including Spanish, German, Hindi, French, Chinese, Russian,
+and Japanese, and we're always excited to add more. If you speak a
+language other than English, your help with translating Zulip would be
+greatly appreciated!
+
+If you are interested in knowing about the technical end-to-end
+tooling and processes for tagging strings for translation and syncing
+translations in Zulip, read about [Internationalization for
+Developers](internationalization.md).
+
+## Translators' workflow
+
+These are the steps you should follow if you want to help translate
+Zulip:
+
+1. Join [#translation][translation-channel] in the [Zulip development
+   community server](https://zulip.com/development-community/), and say hello.
+   That channel is also the right place for any questions, updates on your
+   progress, reporting problematic strings, etc.
+
+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** 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. Navigate to the [Zulip project on Weblate](https://hosted.weblate.org/projects/zulip/).
+
+1. Choose the language you'd like to translate into; your preferred
+   languages should be at the top.
+
+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).
+
+   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 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:
+
+- Follow your language's [translation guide](#translation-style-guides).
+  Keeping it open in a tab while translating is very handy. If one
+  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.
+
+- 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/).
+
+- Pay attention to capital letters and punctuation. Details make the
+  difference! Weblate will catch, and warn about, some cases of
+  mismatched punctuation.
+
+- 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 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
+
+This section assumes you have a
+[Zulip development environment](../development/overview.md) set up;
+if setting one up is a problem for you, ask in chat.zulip.org and we
+can usually just deploy the latest translations there.
+
+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:
+
+- You can insert the language code as a URL prefix. For example, you
+  can view the login page in German using
+  `http://localhost:9991/de/login/`. This works for any part of the
+  Zulip UI, including portico (logged-out) pages.
+- For Zulip's logged-in UI (i.e. the actual web app), you can [pick the
+  language](https://zulip.com/help/change-your-language) in the
+  Zulip UI.
+- If your system has languages configured in your OS/browser, Zulip's
+  portico (logged-out) pages will automatically use your configured
+  language. Note that we only tag for translation strings in pages
+  that individual users need to use (e.g., `/login/`, `/register/`,
+  etc.), not marketing pages like `/features/`.
+- In case you need to understand how the above interact, Zulip figures
+  out the language the user requests in a browser using the following
+  prioritization (mostly copied from the Django docs):
+
+  1. It looks for the language code as a URL prefix (e.g., `/de/login/`).
+  1. It looks for the cookie named 'django_language'. You can set a
+     different name through the `LANGUAGE_COOKIE_NAME` setting.
+  1. It looks for the `Accept-Language` HTTP header in the HTTP request
+     (this is how browsers tell Zulip about the OS/browser language).
+
+- Using an HTTP client library like `requests`, `cURL` or `urllib`,
+  you can pass the `Accept-Language` header; here is some sample code to
+  test `Accept-Language` header using Python and `requests`:
+
+  ```python
+  import requests
+  headers = {"Accept-Language": "de"}
+  response = requests.get("http://localhost:9991/login/", headers=headers)
+  print(response.content)
+  ```
+
+  This can occasionally be useful for debugging.
+
+### 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 **Automatic suggestions** tab below the translation box.
+
+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
+
+We maintain translation style guides for Zulip, giving guidance on how
+Zulip should be translated into specific languages (e.g., what word to
+translate words like "channel" to), with reasoning, so that future
+translators can understand and preserve those decisions:
+
+- [Chinese](chinese.md)
+- [Finnish](finnish.md)
+- [French](french.md)
+- [German](german.md)
+- [Hindi](hindi.md)
+- [Japanese](japanese.md)
+- [Polish](polish.md)
+- [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
+translate, and doing so greatly increases the ability of future
+translators to update the translations in a consistent way. See [our
+docs on this documentation](../documentation/overview.md) for how to
+submit your changes.
+
+### Capitalization
+
+We expect that all the English translatable strings in Zulip are
+properly capitalized in a way consistent with how Zulip does
+capitalization in general. This means that:
+
+- The first letter of a sentence or phrase should be capitalized.
+  - Correct: "Channel settings"
+  - Incorrect: "Channel Settings"
+- All proper nouns should be capitalized.
+  - Correct: "This is Zulip"
+  - Incorrect: "This is zulip"
+- All common words like URL, HTTP, etc. should be written in their
+  standard forms.
+  - Correct: "URL"
+  - Incorrect: "Url"
+
+The Zulip test suite enforces these capitalization guidelines in the
+web app codebase [in our test
+suite](../testing/testing.md#other-test-suites)
+(`./tools/check-capitalization`; `tools/lib/capitalization.py` has
+some exclude lists, e.g., `IGNORED_PHRASES`).
+
+[translation-channel]: https://chat.zulip.org/#narrow/channel/58-translation