Skip to content

GitLab

Last edited by emmapeel
Page history

Localization for developers

Translation process for Tor Project developers

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.

If you have doubts about how to localize your software, please get in touch with emmapeel@torproject.org

Table of contents

How to be nice to translators

Remember that if you generate better quality source strings, the translations will be better.

Translators' input

Translators find many errors on the source strings, it is important to have a look at the open issues in transifex (needs login)

After selecting a string, check the Comments section on the bottom right: there you will see the issue the translator has found:

issues_transifex.cleaned

Please read the incredibly good article [https://www.smashingmagazine.com/2012/07/12-commandments-software-localization/ 12 Commandments Of Software Localization] from Zack Grossbart to get an introduction to software localization from an engineer's point of view. This are developers best practices with l10n in mind:

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.

2. PUNCTUATION IS PART OF THE SENTENCE

Please add all punctuation for translation, as different languages use different punctuation rules. Punctuation is part of the sentence.

3. NO HARDCODED UPPERCASES OR CAPITALIZATION

Ortographic rules change depending on a word being capitalized or not in many languages, as Greek and Russian. Other languages, like Arabic, don't even have capital letters, so your styling will not be seen.

That is why you should refrain of hardcoding this styles on CSS or other similar way, and if you want a capitalized sentence, write the actual sentence capitalized as you would like to see it, so the translator understands what you want, and translates your intention on the local rules (maybe adding exclamation signs).

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 a developer comment explaining how to translate it is needed.

You can also upload screenshots to the strings. That will improve greatly the quality of translations.

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, to give the correct gender to the adjective.

5. PROVIDE SCREENSHOTS AND EARLY LOCALIZED RESOURCES

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.

The localization coordinator can add the screenshots and map them to the strings, but you need to provide them. Screenshots with error messages should especially be present.

Release an alpha to test translations as the Tor Browser team does. For the websites, we have separated versions with more languages so translators can preview their work.

Getting your translations added to Transifex

Imagine a timeline a bit like this:

%%{init: { 'theme': 'forest' } }%%
gantt
    title Localization process
    dateFormat  YYYY-MM-DD
    section Before
    Research for i18n options :a1, 4d
    Test formats     : a3, after a1, 2d
    section Translation
    Translation      : a4, after a3, 40d
    Review      : a5, after a3, 50d
    More translations: a12, after a4, 2d
    Upstream translators input: b1, after a12, 5d
    Section Maintenance
    Software updates: a6, after a5, 2d
    Small translations: a7, after a6, 20d
    Software updates: a8, after a7, 1d
    Small translations: a9, after a8, 20d
    Software updates: a10, after a9, 1d
    Small translations: a11, after a10, 20d

Prepare your files for translation

  • Check [Transifex] for supported file types
  • Our Tier 1 languages contain languages that are read from right to left (RTL). Make sure that your interface can support that.
  • Open a ticket in the component Community/L10n with a link to a file in a repository with your English strings.
  • Please attach screenshots for all the strings, or better, upload them to transifex.
  • Contact emmapeel <at> torproject <dot> org and she will make the bot pick them up and produce two branches on the translation repository
  • Wait for strings to be added to Transifex 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, or review those strings carefully.
  • Transifex does not provide of QA on the strings. You will need to apply your own validation scripts to the strings coming from transifex.
  • Please think about right-to-left languages.

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 will need to wait for a new (shorter) round of translations for the strings you correct.
  • Translators meet once a month, maybe you want to drop by the next Monthly Tor Localization Hangouts to explain what your app does and talk to translators.
  • You can check the process of your app translation in Transifex, joining the Tor Project there. Open an account 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.

Transifex Sandbox

For developers, there is a sandbox available to test translations and start integration, before having the projects sent to the translators.

If you would like to test your applications there, please open an account and ask for access to the L10n Coordinator.

On the Sandbox you will be able to upload translation files and see how the strings look for the translators. Please check that the comments for translators are well placed and understandable.

Your translations

  • Clone the [https://gitweb.torproject.org/translation.git translation repository]
  • Check out the branch for your project (e.g. ''git checkout mat-gui'')
  • If you only want translations that are completed, check out the ''_completed'' branch instead (e.g. ''git checkout mat-gui_completed''). Currently this branch only provides reviewed strings as well.

'''NOTE:''' Transifex does '''not''' do any kind of input validation on the translated strings. You need to make sure that the strings you include are valid and do not contain anything malicious.

Stats

arthuredelstein is helping with some stats about translation, so they can be accessed from outside transifex:

thanks arthur!

How do we call the languages?

Call them as they call them

When we present a list of languages, we like to call them as the speakers of that language call them. Because if they don't speak English, they probably don't know how their language is spell in English (specially if they use other kind of characters).

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

tbb Lang code transifex English name Preferred name (orig) Notes
ar Arabic عربية (ar)
bn Bangla/Bengali বাংলা Bangla from Bangladesh and from India are very similar
ca Català (ref #31600 (closed))
cs česky
da Dansk
de Deutsch
el Ελληνικά (el)
en-US en This is our default source language.
en-GB en_GB We will not provide this language.
es-AR 2021-03: dropped in favor of common es locale
es-ES es Español (es)
et et Estonian Eesti (et)
fa ﻑﺍﺮﺳی (fa)
fr Français (fr)
ga-IE ga Irish Gaeilge (ga)
he Hebrew עברית (he)
hi Hindi हिन्दी (hi) We still have no published translations for Hindi
hr Croatian hrvatski (hr)
hu Hungarian Magyar nyelv (hu)
id bahasa Indonesia (id)
is Icelandic Íslenska (is)
it Italiano
ja 日本語
ka Georgian ქართული ენა
ko 한국어
lt Lithuanian lietuvių
mk Macedonian македонски (mk)
ml Malayalam മലയാളം
ms ms_MY Malay Bahasa Melayu
my my Burmese မြန်မာ (my)
nb-NO Norwegian Norsk bokmål
nl Dutch Nederlands (nl)
pl Polish polski
pt-BR Português Br.
pt-PT Português Port.
ro Romanian Română
ru Russian Русский
sv-SE sv Swedish Svenska (sv)
sw sw Swahili Swahili (sv) Waiting on Firefox to provide translation for Tor Browser, local group translating the Tor Browser Manual atm.
th Thai ภาษาไทย (th)
tr Türkçe
vi Tiếng Việt
uk українська
zh-CN zh_CN 简体中文 (zh-CN)
zh-TW zh_TW 正體字 (zh-TW)