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.

This page is not intended to be a substitute for on-line discussion. You can contact translatewiki.net staff live on the IRC channel #mediawiki-i18n at freenode.

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.

See also:
 * Mozilla i18n and L20n
 * Review of Gettext po(t) file format

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 "continuous translation" or "continuous localization" to mean translating the wiki way.

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
All messages and requests about supported projects are placed on Support. We use Support to track requests which need attention/action and help the developers/project managers find them.

After a few weeks at most, all the threads belonging to one of the supported projects (whether resolved or not) will be moved to their talk pages by the maintainers of Support. In addition to that, and if possible before moving, the above-mentioned template should be added and updated as soon as possible so that threads are shown in several relevant places, including the global list Support/Open requests.

Assuming that's been done correctly, some neat things can happen, see for instance the following tutorial:
 * File:Handling translatewiki support requests.webm (2 minutes: how to reply to threads)

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 happens semi-regularly, usually every 2-4 weeks 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. More internal details can be found at Repository management and related pages.

Some example exports for various formats:
 * .properties,
 * YAML,
 * JSON.

Languages, messages, editing, translator issues
All this and more is covered in the FAQ.
 * FAQ and Translatewiki.net languages
 * FAQ
 * FAQ
 * FAQ
 * Plural, Gender, Grammar

Message identification
Messages at 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  (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 when they hit the "" button for the message.

The message documentation page is usually written manually. Programmers are encouraged to contribute to the message documentation. Useful information includes:
 * 1) message handling (parsing, escaping, plain text, etc.)
 * 2) types of parameters with example values
 * 3) where the message is used (pages, locations in the user interface, e-mails sent to users, etc.)
 * 4) how the message is used where it is used (a page title, button text, etc..)
 * 5) which other messages are used together with this message, or which other messages this message refers to, with links
 * 6) 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)
 * 7) 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 where this has to be enabled for individual messages, etc.
 * 8) parts of the message which must not be translated, such as generic namespace names or URLs
 * 9) translation hints such as synonyms for terms, the grammatical function of a short message (mainly whether a noun or verb), etc.
 * 10) a link to a definition of any website-specific technical terms. Glossaries are not yet integrated into the documentation system.
 * 11) 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 you will need translator rights, which can be requested at Project:Translator.

Alternatively, developers can modify the message files directly, although making the changes here in translatewiki.net would be awesome.

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.

Other message documentation displayed automatically on the message edit page includes:
 * 1) Links to other messages with the same or similar wording
 * 2) The name of the extension to which it belongs, linked to the description page of the extension on the project or on translatewiki.net.

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).

Types of Context
Context can be divided into following categories:
 * 1) 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.
 * 2) Social context — This can be defined in terms of objective social variables like class, gender, persons, social identity etc.
 * 3) 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.
 * 4) 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:
 * 1) Co-text — Portion of the text, surrounding sentences
 * 2) Rel-text — Related text, fixing a problem is difficult; eg terminology, style guide
 * 3) Chron-text — Versions of a text
 * 4) Bi-text — Bi-lingual resources, translation memory
 * 5) 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:
 * 1) Protocols — Protocols should be essentially commented especially when it appear as URI. eg. help:index. Protocol responses should also be taken care with proper contextual comments. eg. “Server returned HELLO”
 * 2) File names — File name should be commented. eg. fuel.txt
 * 3) Program Names — Program name should be commented. eg. firefox
 * 4) Ambiguous words — Particularly a word that can be used in different forms like verb as well as noun. eg. empty
 * 5) Environment variables — Environment variables should be intact and so context should be provided. eg. LANG=hi_IN.utf8
 * 6) Abbreviation & Acronyms — Generally it would be a better practices to give context for Abbreviation & Acronyms. eg. l10n, m17n, FIR
 * 7) Config Files Entries — Config Files Entries should be given context. eg. publican config file entries:
 * surname: 
 * firstname: 
 * email: 
 * langs: 
 * lang: 
 * lang: 

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.

Links to advice on other websites

 * Globalvis
 * MediaWiki
 * mw:Help:Extension:Translate/Translation best practices