To have a real impact worlwide, our software needs to break the language barriers a **majority of the global population** has.
Localizing our software let us share it with more people, and should eventually lead to better software in itself, even if it needs a bit more work.
To have a real impact worlwide, our software needs to break the language barriers a **majority of the global population** has. Localizing our software let us share it with more people, and should eventually lead to better software in itself, even if it needs a bit more work.
The process of making code translatable is called **internationalization (i18n)**. This is what you, as a developer, will do.
...
...
@@ -17,14 +16,12 @@ If you have doubts about how to localize your software, please get in touch with
Remember that **if you generate better quality source strings, the translations will be better**.
### Translators' input
Translators find many errors on the source strings.
If you create an account in weblate, you can set up [notifications](https://hosted.weblate.org/accounts/profile/#notifications) for the resources in weblate.
### Learn more about Internationalization
If this is the first time you are implementing the internationalization of a project, please start by having a look at this resources:
...
...
@@ -32,7 +29,7 @@ If this is the first time you are implementing the internationalization of a pro
- This is a very informative talk from [Tom de Moor at FOSDEM2024](https://fosdem.org/2024/schedule/event/fosdem-2024-1906-lessons-learnt-as-a-translation-contributor-the-past-4-years/)(only 30m) with lots of information for developers.
- Please read the incredibly good article [12 Commandments Of Software Localization](https://www.smashingmagazine.com/2012/07/12-commandments-software-localization/) from Zack Grossbart to get an introduction to software localization from an engineer's point of view.
- Another great article is [Lessons From Linguistics: i18n Best Practices for Front-End Developers by Lucas Huang ](https://shopify.engineering/internationalization-i18n-best-practices-front-end-developers)(thanks Thorin for showing it to me).
- For RTL support, please read [rtl.wtf](https://rtl.wtf) and [isthisarabic.com](https://isthisarabic.com)
- For RTL support, please read rtl.wtf and isthisarabic.com
#### 1. NEVER CONCATENATE STRINGS
...
...
@@ -66,14 +63,12 @@ If Weblate is not catching and error of the translation, please let the Localiza
The translators will translate better if they can see the effect their translations have. Try to get a staging/beta version early, so they can do a final review for the language with the real application.
Add screenshots to the translation platform so the translators see how the words will look on the interface.
This will improve the translation because the translators will have the context of the strings, and can also translate looking at the interface.
Add screenshots to the translation platform so the translators see how the words will look on the interface. This will improve the translation because the translators will have the context of the strings, and can also translate looking at the interface.
To learn how to add screenshots easily, please read [Adding screenshots](Localization-for-developers/Adding-screenshots).
Release alphas or nightlies to test translations while they are in progress, as the Tor Browser team does. For the websites, we have separated versions with more languages so translators can preview their work before release. Many of our translators are inexperienced and this helps them learn quickly how to translate without errors.
# Getting your translations added to weblate
Imagine a timeline a bit like this:
...
...
@@ -105,25 +100,32 @@ gantt
* Check [weblate](https://docs.weblate.org/en/latest/formats.html) for supported file types
* You will need to wait for a new (shorter) round of translations for each string you change. Changing small details for the strings will render them untranslated and create more work. Please only send strings for translation once they are final.
* Our Tier 1 languages contain languages that are read from right to left (RTL). Make sure that your interface can support that. Remember that RTL also implies page composition, align and all. See https://rtl.wtf/intro/ and https://rtlstyling.com/posts/rtl-styling/ to understand the issue.
* Open a ticket in the component [Community/L10n](https://gitlab.torproject.org/tpo/community/l10n/-/issues) with a file with your English strings.
* Open a ticket in the component [Community/L10n](https://gitlab.torproject.org/tpo/community/l10n/-/issues) with a file with your English strings. If the string is in a repository, we can setup an alert to update our file when there are changes.
* Please **attach screenshots** for all the strings, so they can be uploaded to weblate. You can have several strings on one screenshot, but try to make sure all strings are present. More information on the Screenshots section.
* Contact `emmapeel <at> torproject <dot> org` and she will make the bot pick them up and produce a branch on the [translation repository](https://gitlab.torproject.org/tpo/translation/)
* Wait for strings to be added to weblate and git
* Remember that our translators are volunteers interested to help software be on their language. They are usually just starting to translate and may not have a technical background, so strings with variables or even HTML may lead to errors. Try to make the strings not overtly complicated, and add comments explaining the string, or review the strings carefully.
* Weblate does provide some[ QA on the strings](https://docs.weblate.org/en/latest/user/checks.html#checks-and-fixups), but difficult strings can have special checks added. You may need to apply your own validation scripts to the strings coming from weblate.
* Wait for strings to be added to weblate and git.
* Remember that our translators are volunteers interested to help software be on their language. They are usually just starting to translate, and may not have a technical background, so strings with variables or even HTML may lead to errors. Try to make the strings not overtly complicated, and add comments and screenshots explaining the string, or review the strings carefully.
* Weblate does provide some[ QA on the strings](https://docs.weblate.org/en/latest/user/checks.html#checks-and-fixups), but difficult strings can have special checks added. You may need to apply your own validation scripts to the strings coming from weblate. If your validation scripts pick up errors not discovered in weblate, please contact the Localization Coordinator, as we should report this upstream.
#### During the translation process
* Please go back to the strings after a while, to see the comments the translators have made on the strings. Translators find errors on the source strings very often. You can also setup different [notifications in weblate](https://hosted.weblate.org/accounts/profile/#notifications) to be aware of problems with your translation: from new comments to repository failures.
* Please go back to the strings after a while, to see the comments the translators have made on the strings. Translators find errors on the source strings very often, sometimes their questions are related to the UX changes.
* You can setup different [notifications in weblate](https://hosted.weblate.org/accounts/profile/#notifications) to be aware of problems with your translation: from new comments to repository failures.
* Translators meet once a month, maybe you want to drop by the next [Monthly Tor Localization Hangouts](./Monthly-Tor-Localization-Hangouts) to explain what your app does and talk to them about the app. This will get translators engaged on your software and you will get alpha testers for free!
* You can check the process of your app translation in weblate, joining the Tor Project there. [Open an account](https://community.torproject.org/localization/becoming-tor-translator/) and ping the Localization Coordinator to get more privileges.
* Remember: translations are always better when translators have access to screenshots and previews. Releasing an alpha version with all the active translations will help translators to spot any errors with their translations.
* You can check the process of your app translation in weblate, joining the Tor Project there. [Open an account](https://community.torproject.org/localization/becoming-tor-translator/) and ping the Localization Coordinator to get more privileges. You will be able to:
* Disable failing strings
* Answer to comments
* Approve suggestions for translation
* Add screenshots
* Search and replace
* Remember that **translations are always better when translators have access to screenshots and previews**. Releasing an alpha version with all the active translations will help translators to spot any errors with their translations.
### Your translations
* Clone the [translation repository](https://gitweb.torproject.org/translation.git)
* Check out the branch for your project (e.g. ''git checkout mat-gui'')
'''NOTE:''' Weblate does '''not''' do much validation on the translated strings. You need to make sure that the strings you include are valid and do not contain anything malicious.
'''NOTE:''' Weblate does some validation on the translated strings, depending on format and configuration. If you have strings that always give problems when building, we can enforce validation rules and make sure translators understand how to translate. We can also setup checks to make sure that fingerprints, emails, are not replaced by translators.
### Stats
...
...
@@ -131,8 +133,6 @@ gantt
* You can also use the weblate API: https://docs.weblate.org/en/latest/api.html
* There are some stats in [this wiki](https://gitlab.torproject.org/tpo/community/l10n/-/wikis/Localization-for-translators#tor-documents-to-translate)
# How do we call the languages?
### Call them as they call them
...
...
@@ -142,18 +142,17 @@ When we present a list of languages, we like to call them as the speakers of tha
We can easily read Spanish/English because we share a Latin alphabet. People using another kind of alphabets (Arabic, Cyrillic, Georgian, etc) will look for familiar letters before reading.
### language codes: Always better to follow Mozilla
Many of our applications depend on the Tor Browser, which in turn depends on Mozilla. By making sure your apps will expect the language codes as in mozilla, you can ensure links and other things are going to work across the whole project. See here for Mozilla language codes: https://hg.mozilla.org/l10n-central/ . Check with the localization coordinator if you don't know what is the situation with your app.
Incidentally, transifex may differ from this codes, but we can correct that through our translation repo. For example, we use `en-US` for the Tor Browser default English locale, but it is called `en` in Transifex.
### Current language list
This is a list of languages we use along projects, with notes about how to write them etc.
Another version of this list can be found at https://gitlab.torproject.org/tpo/community/l10n/-/blob/main/bin/setup_l10n_staging.py
This is a list of languages we use along projects, with notes about how to write them etc. Another version of this list can be found at https://gitlab.torproject.org/tpo/community/l10n/-/blob/main/bin/setup_l10n_staging.py
| tbb Lang code | Weblate | English name | Preferred name (orig) | Notes |
| ku | | Kurdish | Umbrella term, it is better to use ckb, Central Kurdish |
| ku | | Kurdish | Umbrella term, it is better to use ckb, Central Kurdish | |
| ky | | Kyrgyz | Кыргыз тили (ky) | This is the official language of Kyrgyzstan and a significant minority language in the Kizilsu Kyrgyz Autonomous Prefecture in Xinjiang, China and in the Gorno-Badakhshan Autonomous Region of Tajikistan. There is a very high level of mutual intelligibility between Kyrgyz, Kazakh, and Altay |
| ln | | Lingala | Lingála (ln) | Spoken in DRC, Congo, Sudan and Angola. |
| lo | | Lao | ພາສາລາວ (lo) | |
...
...
@@ -213,7 +212,7 @@ Another version of this list can be found at https://gitlab.torproject.org/tpo/c
| ps | | Pashto | (ps) پښتو | |
| pt-BR | pt_BR | | Português Br. | |
| pt-PT | pr_PT | | Português Port. | |
| rn | | Kirundi | Ikirundi (rn) |
| rn | | Kirundi | Ikirundi (rn) | |
| ro | | Romanian | Română (ro) | |
| ru | | Russian | Русский (ru) | |
| rw | | Kinyarwanda | Kinyarwanda (rw) | |
...
...
@@ -241,7 +240,6 @@ Another version of this list can be found at https://gitlab.torproject.org/tpo/c
| zh-CN | zh_Hans | Chinese (China) | 简体中文 (zh-CN) | Also called Simplified Chinese - Chinese Hans - language name changed, ref: tpo/community/l10n#40108 |
| zh-TW | zh_Hant | Chinese (Taiwan) | 正體中文 (zh-TW) | Also called Traditional Chinese - Chinese (Hong Kong) - Chinese Hant |
