2012-05-01: Support was added for Waymarked Trails. (Other news...)
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.
Contents |
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:
- 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 FreeColtranslators 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.
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.
Message identification
Messages at translatewiki.net are referred to using message names, also called messge 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 when they hit the "Edit" button for the message.
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 where this has to be enabled for individual messages, 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 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:
- Links to other messages with the same or similar wording
- The name of the extension to which it belongs, linked to the description page of the extension on the project or on translatewiki.net.
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.
