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.
...
...
@@ -11,12 +10,11 @@ If you have doubts about how to localize your software, please get in touch with
**Table of contents**
[[_TOC_]]
[[_TOC_]]
# How to be nice to translators
Remember that **if you generate better quality source strings, the translations will be better**.
Remember that **if you generate better quality source strings, the translations will be better**.
### Translators' input
...
...
@@ -24,17 +22,16 @@ 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:
- 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)
- 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 and isthisarabic.com
#### 1. NEVER CONCATENATE STRINGS
#### 1. NEVER CONCATENATE STRINGS
It may sound efficient in English, but the truth is that different languages have different ways of saying things, and the order is important. Please make it so the whole sentences is up for translation at once, don't separate sentences in several strings.
...
...
@@ -52,9 +49,9 @@ That is why you should refrain from hardcoding styles like all caps or camel cas
#### 4. ADD COMMENTS OR EXPLANATIONS ON HOW TO TRANSLATE
Context is everything when translating, and if a string has many errors, it probably means that more context is needed.
Context is everything when translating, and if a string has many errors, it probably means that more context is needed.
Some strings need screenshots to be well translated. Especially in GUIs, when we translate out-of-context single words.
Some strings need screenshots to be well translated. Especially in GUIs, when we translate out-of-context single words.
When the source text is in English, as on our project, the objects on that language have no gender. But objects have gender in many languages: Spanish, Italian, French, German... So when we translate 'Published' to German, we need to know what was published (a book, a release?), to give the correct gender to the adjective.
...
...
@@ -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:
...
...
@@ -102,28 +97,35 @@ gantt
#### Prepare your files for translation
* 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.
* 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.
* 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. 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 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.
* 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.
* 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. 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'')
* 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,105 +142,103 @@ 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 |
|------ | ------ | ------ | ------ | ------
| am | | Amharic | አማርኛ (am) | Ethiopian language |
| ar | | Arabic | (ar) العربية | Added the article, ref: tpo/community/l10n#40116 |
| az | | Azeri, Azerbaijani | Azərbaycan dili (az) | |
| ba | | Bashkir | Башҡортса (ba) | |
| be | | Belarusian | беларуская мова (be) | |
| bg | | Bulgarian | български (bg) | |
| bn | | Bangla/Bengali | বাংলা | Bangla from Bangladesh and from India are very similar|
| bo | | Tibetan | ལྷ་སའི་སྐད་ (bo) | the last ' is part of the name |
| bs | | Bosnian | Bosanski (bs) | we use the latin version, not cyrillic |
| en-US | en | English | English (en) | This is our default source language, sometimes written as en, but Firefox for example needs a country code as well.|
| en-GB | en_GB | | | We will not provide this locale, preferring to stick to one regional variation. |
| es-AR | | | | 2021-03: dropped in favor of common es locale |
| 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) | |
| lt | |Lithuanian | lietuvių (lt) | |
| mk | | Macedonian | македонски (mk) | |
| ml | | Malayalam | മലയാളം (ml)| |
| ms | ms_MY| Malay | Bahasa Melayu (ms) | |
| my | my | Burmese | မြန်မာ (my) | |
| nd | nd | Ndebele North | isiNdebele (nd) | |
| nb-NO | | Norwegian | Norsk bokmål | |
| nl | | Dutch | Nederlands (nl) | |
| pl | | Polish | polski | |
| ps | | Pashto | (ps) پښتو | |
| pt-BR | pt_BR | | Português Br. | |
| pt-PT | pr_PT | | Português Port. | |
| rn | | Kirundi | Ikirundi (rn) |
| ro | | Romanian | Română (ro) | |
| ru | | Russian | Русский (ru) | |
| rw | | Kinyarwanda | Kinyarwanda (rw) | |
| sg | | Sango | sängö (sg) | |
| sh | | Shona | ChiShona (sh) | |
| so | | Somali | Soomaali (so) | We use the Latin script |
| en-US | en | English | English (en) | This is our default source language, sometimes written as en, but Firefox for example needs a country code as well.|
| en-GB | en_GB | | | We will not provide this locale, preferring to stick to one regional variation. |
| es-AR | | | | 2021-03: dropped in favor of common es locale |
| 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) | |
| lt | | Lithuanian | lietuvių (lt) | |
| mk | | Macedonian | македонски (mk) | |
| ml | | Malayalam | മലയാളം (ml) | |
| ms | ms_MY| Malay | Bahasa Melayu (ms) | |
| my | my | Burmese | မြန်မာ (my) | |
| nd | nd | Ndebele North | isiNdebele (nd) | |
| nb-NO | | Norwegian | Norsk bokmål | |
| nl | | Dutch | Nederlands (nl) | |
| pl | | Polish | polski | |
| ps | | Pashto | (ps) پښتو | |
| pt-BR | pt_BR | | Português Br. | |
| pt-PT | pr_PT | | Português Port. | |
| rn | | Kirundi | Ikirundi (rn) | |
| ro | | Romanian | Română (ro) | |
| ru | | Russian | Русский (ru) | |
| rw | | Kinyarwanda | Kinyarwanda (rw) | |
| sg | | Sango | sängö (sg) | |
| sh | | Shona | ChiShona (sh) | |
| so | | Somali | Soomaali (so) | We use the Latin script |
| sq | | Albanian | shqip (sq) | |
| sr | sr@latin | Serbian | srpski (sr) | We use the Latin script, not cyrillic |
| sv-SE | sv | Swedish | Svenska (sv) | |
| sv-SE | sv | Swedish | Svenska (sv) | |
| sw | sw | Swahili | Kiswahili (sw) | Waiting on Firefox to provide translation for Tor Browser, now translating the Tor Browser Manual, Support Portal, main website, gettor.tpo. |
| ta | | Tamil | தமிழ் (ta) | One of the few classical languages that are still spoken, approx. 80millon's first language. |
| tg | | Tajik | Тоҷикӣ (tg) | |
| tl | | Tagalog | | Preferred to Filipino because it is more used and has a Firefox locale |
| th | | Thai | ภาษาไทย (th) | |
| ti | | Tigrinya | ትግርኛ (ti) | |
| ti | | Turkmen | türkmençe (tk) | we use the latin script |
| tr | | Turkish | Türkçe (tr) | |
| tt | | Tatar | татар (tt) |The Tatar language is spoken in Russia (about 5.3 million people), Ukraine, China, Finland, Turkey, Uzbekistan, the United States of America, Romania, Azerbaijan, Israel, Kazakhstan, Georgia, Lithuania, Latvia and other countries. There are more than 7 million speakers of Tatar in the world. |
| ug | ug@Arab | Uighur | (ug) ئۇيغۇر | The Arabic script is the most used |
| uk | | Ukrainian | українська (uk) | |
| ur | | Urdu | (ur) اُردُو | |
| uz | | Uzbek | Oʻzbekcha (uz) | |
| vi | | Vietnamese | Tiếng Việt (vi) | |
| wo | | Wolof | Wolof (wo) | We use Latin script |
| 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 |
| ta | | Tamil | தமிழ் (ta) | One of the few classical languages that are still spoken, approx. 80millon's first language. |
| tg | | Tajik | Тоҷикӣ (tg) | |
| tl | | Tagalog | | Preferred to Filipino because it is more used and has a Firefox locale |
| th | | Thai | ภาษาไทย (th) | |
| ti | | Tigrinya | ትግርኛ (ti) | |
| ti | | Turkmen | türkmençe (tk) | we use the latin script |
| tr | | Turkish | Türkçe (tr) | |
| tt | | Tatar | татар (tt) | The Tatar language is spoken in Russia (about 5.3 million people), Ukraine, China, Finland, Turkey, Uzbekistan, the United States of America, Romania, Azerbaijan, Israel, Kazakhstan, Georgia, Lithuania, Latvia and other countries. There are more than 7 million speakers of Tatar in the world. |
| ug | ug@Arab | Uighur | (ug) ئۇيغۇر | The Arabic script is the most used |
| uk | | Ukrainian | українська (uk) | |
| ur | | Urdu | (ur) اُردُو | |
| uz | | Uzbek | Oʻzbekcha (uz) | |
| vi | | Vietnamese | Tiếng Việt (vi) | |
| wo | | Wolof | Wolof (wo) | We use Latin script |
| 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 |
