Translating:Localisation for developers

This page contains a collection of advice and information on localisation including management of localisation, mainly for software developers and software project managers. Some of the information here is based on the experiences of translatewiki.net users in collaboration with the developers of supported projects. Links to resources on localisation outside of translatewiki.net are also provided here. If you have good examples of localisation problems, or have found good resources for localisation, please add them to this page. If you are interested in using translatewiki.net to localise your project please read the page on new projects.

Principles

The following principles are closely related and largely at the base of all the rest.

Translators should translate

If you want a good translation, you need translators. If you require programming, you'll get coders instead.

Translating the wiki way

Translating the wiki way means being like wikis: low barriers to translate, translations used immediately, a forgiving system to improve translations.

MediaWiki translation is made by hundreds translators, using a simple syntax: it doesn't take a coder to add strings to MediaWiki, or translate them; translations go live on MediaWiki wikis within 24-48 hours from the moment English messages are added; users, translators and developers get instant feedback from each other.

i18n must not be an afterthought

Translating the wiki way means that i18n (and feedback from it) informs your development from the beginning; your product is made in partnership with translators.

Continuous translation

Some say "agile translation", "agile localization", "continuous translation" or "continuous localization" to mean translating the wiki way.

See for instance Co-creating a repository of best-practices for collaborative translation:

Agile translation teamware: wiki-like systems and processes that allow multidisciplinary teams of professionals (translators, terminologists, domain experts, revisers, managers) to collaborate on large translation projects, using an agile, grassroots, parallelized process instead of the more top-down, assembly-line approach found in most translation workflow systems.

Some more references are available from Internationalisation and localisation of spoken dialogue systems and in w:Internationalization and localization.

Management of supported projects

Project page

The main project management tool is the project page and its talk page. The project pages contain information useful to both project managers and translators including:

name, logo and short description of the project
project statistics
name of translatewiki.net coordinator for the project
details of how to contact the project itself, and whom to contact. Some projects have forums specializing on the localisation of the project, or e-mail lists like the FreeCol-translators mailing list ,
links to general project documentation and screenshots, useful for translators in understanding what they are translating
notes on PLURAL or GRAMMAR support available on the project
notes on translation flow, including frequency of 'commits' and frequency of software updates of the project
the localisation threshold
sub-pages with project documentation such as a glossary of project-specific terminology
the project talk page is usually the first place where translators can discuss project matters with developers. Translators can report suspected errors in the source message, and request clarification of a message, or request PLURAL, GRAMMAR or GENDER support, where available
optionally, a link to the public repository and issue tracker and a mention of the license used.

Things which contribute to efficient and good quality localisation

Good communication between translatewiki.net and the project. Where no answers to posts on the talk page are forthcoming, translators may try to contact the project directly, or may just end up discouraged.
Good documentation
The speedy appearance of translations in the project releases. If a link to software release notes or logs is provided, then translators can check progress. This helps to provide the motivation to translators to continue translating.
Feedback from the project end-users to the translators. Where a project uses technical terms which may already have been localised, then a way should be set up for end-users to provide the correct localised technical terms to the translators. For example, pointing potential contributors a project specific glossary page might be an option.

Support requests

For a successful localisation of your project, it's essential to have effective communication between translators and developers. Translators are often the first to notice an unclear interface or other issue with your software. MediaWiki discussions allow translators to cooperate on individual translations and overall project goals, but developers need to be within reach to provide the necessary context and code fixes, as early as possible in the translation process, to reduce wasted work.

By default, all messages and requests about supported projects are placed on Support. Some wiki features like {{Support}} may be used to track requests which need attention/action and help the developers/project managers find them. Alternatively, it's also possible to send translators directly to your project's issue tracker, if that's easy to use for our translators (for instance Phabricator allows login with a Wikimedia account).

Export

The translations are committed to your project's repository by translatewiki.net staff because this phase is usually seamless on the project's end, while the sync needs care to protect translatewiki.net itself. Export is manually-initiated and happens semi-regularly, usually twice a week or when there is a particular need (e.g. upcoming release, many new translations).

The commit phase is usually called "export", while "sync" is the import of new strings: the two are independent and syncs are often more frequent (daily, often automatically as of 2016). More internal details can be found at New project setup, Repository management and related pages.

Some example exports for various formats:

.properties,
YAML,
JSON (browse all MediaWiki JSON l10n files).

Languages, messages, editing, translator issues

All this and more is covered in the FAQ.

Message identification

Messages at translatewiki.net are referred to using message names, also called message keys. If a project does not have any yet, they can be generated automatically. Forming message keys, it is best to use only lower case letters, digits, hyphens and dots, since many other characters tend to be impractical or give problems in a MediaWiki context.

It is wise to group messages by context of appearance, and keep them in an order in which they appear in reality. If possible, message keys should be used to indicate grouping. This both helps translators to more consistent and better quality.

Message reuse should be avoided in most instances. Even if message texts are equal in the original language, translations may be not, and may need to reflect contexts of use. For identical message texts being translated identically as well, copy and paste and translation memories support translators to be very efficient.

Message documentation

In splitting text strings into individual "messages", the context essential to translation is lost. In order to restore enough context to ensure successful translation, documentation is written manually for the messages. It is conveyed using a pseudo-language, having the code qqq (message documentation). This is one of the ISO 639 codes reserved for private use. This code is used to record message documentation in English, which is visible to translators.

The message documentation page is usually written manually. Programmers are encouraged to contribute to the message documentation. Useful information includes:

message handling (parsing, escaping, plain text, etc.)
types of parameters with example values
where the message is used (pages, locations in the user interface, e-mails sent to users, etc.)
how the message is used where it is used (a page title, button text, etc.)
which other messages are used together with this message, or which other messages this message refers to, with links
anything else which could be understood if the message were seen in context, but not when the message is displayed alone (which is the case when it is being translated)
special properties of the message, such as a page name requiring an initial capital letter; that it should not be a direct translation; that it supports PLURAL or GRAMMAR (in MediaWiki), etc.
parts of the message which must not be translated, such as generic namespace names or URLs
translation hints such as synonyms for terms, the grammatical function of a short message (mainly whether a noun or verb), etc.
a link to a definition of any website-specific technical terms. Glossaries are not yet integrated into the documentation system.
a link to a page using the message, or to a screenshot of the page

The last item often provides enough information on its own, without having to write all of the other documentation.

In order to edit a qqq documentation message in translatewiki.net you will need to have an account. You can choose Message documentation as the translation language to easily find messages that lack documentation. Alternatively, developers can modify the qqq message files directly.

Projects that use GNU gettext can use a method whereby comments in the source code are picked up by gettext tools, and the Translate extension forwards those comments into an uneditable part of message documentation.

Generalities on giving context

Text originally from FUEL Project & Rajesh Ranjan, Context in Technical Translation Concept and Guidelines, 10 April 2013 (CC-BY-SA 3.0). (The linked content on "Fedorahosted.org" is no longer available, replaced in 2017 by the announcement for the retirement of the former FUEL project, without any backup link left in history; the text below is an old summary which may be adpted now for use in translatewiki.net or related projects. FUEL itself was a supported project in translatewiki.net, where it has also been discontinued on 6 April 2018.)

Types of context

Context can be divided into following categories:

Verbal context — It is related to the text or talk of an expression surrounded to the text. The expression can be anything: words, sentences, speech etc.
Social context — This can be defined in terms of objective social variables like class, gender, persons, social identity etc.
Syntagmatic contexts — When semantics of a phrase or word is determined mainly by context, then the context is called syntagmatic context. More than 95 % of vocabularies a person knows comes from syntagmatic context.
Paradigmatic contexts — Paradigmatic contexts concentrates on dictionary meanings that is analyzed within semantic relationship. It is also called lexematic context.

Five aspects of context

Linguists Alan K. Melby and Christopher Foster believe that for all practical purposes context consists of the following five factors that they think are relevant to the understanding of source text and the production of target text. As per their definition these are here:

Co-text — Portion of the text, surrounding sentences
Rel-text — Related text, fixing a problem is difficult; eg terminology, style guide
Chron-text — Versions of a text
Bi-text — Bi-lingual resources, translation memory
Non-text — Beyond text, para linguistic information; eg. intent, audiences, purposes

Where we often need context

There are some obvious places where translators need comments essentially. Here are some of them:

Protocols — Protocols should be essentially commented especially when it appear as URI.
E.g. help:index. Protocol responses should also be taken care with proper contextual comments.

E.g. “Server returned HELLO”
File names and URIs — File name should be commented (they may be partly translatable or unchangeable and with embedded fields with specific formats).
E.g. fuel.txt, logo-en.png
Program Names — Program name should be commented (notably to avoid confusions between product names and translatable common words).
E.g. Firefox
Ambiguous words — Particularly a word that can be used in different forms like verb, noun, or adjective.
E.g. empty, free, clear, state, ...
Environment variables — Environment variables should be intact and so context should be provided.
E.g. LANG=hi_IN.utf8
Abbreviation and acronyms — Generally it would be a better practices to give context for abbreviation and acronyms, as they are frequently ambiguous (and not always translatable).
E.g. l10n, m17n, FIR, CSV, CVS (these last two are correct but for very different meanings and usages, they may appear together within the same sentence!)
Config files entries — Individual entries in configuration files should be given context.
E.g. publican config file entries:

--------------------------------

surname: <YourSurname>

firstname: <YourFirstname>

email: <YourEmailAddress>

langs: <YourLanguage>

lang: <YourLanguage>

---------------------------------

Adaptation of source messages

Translators are asked to suggest improvements to messages and corrections to grammar in the source messages, as they are spotted during the translation process. Translators also propose the addition of PLURAL and GRAMMAR support to a message where needed, if possible. Proposals for amending messages are posted on the project talk page at translatewiki.net or on the project website.

In the Translate UI, the panel displayed on the right of the interface should contain a link pointing to a relevant place for filing such issues, just below the suggested translations after the documentation of each message. Translators are encouraged to post a short FIXME message explaining issues and containing a tracking link to the bug report (submitted either on the project bug tracker site, or on the Support otherwise, or by any contact made with project maintainers listed in each project page on translatewiki.net). Once the issue in source messages is solved, that FIXME can safely be removed from their associated "/qqq" documentation subpage. Projects that don't have working contact links in messages or in project pages should be signaled on the Support page.

Guidance on i18N and L10n

Links to advice on other websites

Examples of common problems