Localisation/cs


 * O lokalizačním týmu Nadace Wikimedia se píše na .
 * Jak se překládají stránky této wiki objasní .

Toto je technický popis internacionalizace a lokalizace (i18n a L10n) MediaWiki. Obsahuje rady a doporučení, kterých by se měli držet vývojáři. Naše mantra je, že se i18n nemá implementovat dodatečně: je to klíčová součást, která by měla být součástí vašeho software od samého počátku, neboť patří mezi základní MediaWiki.

translatewiki.net
translatewiki.net podporuje překlady všech zpráv z jádra, rozšíření a témat, prostřednictvím překladatelských nástrojů, které nabízí wiki. Pokud se nechcete zaobírat technickými detaily ohledně editace souborů, Git, vydávání záplat a tak podobně, jděte rovnou na translatewiki.net.

Veškeré překlady zpráv uživatelského rozhraní MediaWiki by měly projít skrz translatewiki.net, neměly by být vkládány přímo do kódu. Ve zdrojovém kódu je vhodné pracovat pouze s anglickými zprávami a jejich dokumentací.

Jádro MediaWiki a jeho rozšíření musí k zobrazování veškerého textu uživatelského rozhraní využívat systémové zprávy. Příklad, jak na to, najdete zde:. Pokud je rozšíření napsáno správně, pravděpodobně se v objeví během několika dní poté, co o něm odpovědné osoby dají vědět na. Pokud si rozšíření nikdo nevšímá, dejte o tom vědět. Pokud je rozšíření pro překlad zatím nevhodné, zanechte o tom zprávu v kódu a uvědomte odpovědné osoby, je-li to nutné.

Vizte také Přehled lokalizačního systému a Co lze lokalizovat.

Hledání zpráv
demonstruje, jak můžete najít řetězec, který chcete přeložit. Povšimněte si zejména, který byl zaveden v.

E-mailová konference i18n
K odběru zpráv se můžete přihlásit zde: i18n. V danou chvíli je provoz nízký.

Struktura kódu
Nejprve máte jazykový objekt v. Tento objekt obsahuje všechny lokalizovatelné. Obsahuje i další důležitá nastavení specifická pro jazyk a vlastní chování (velká písmena, malá písmena, data tisku, formátovací čísla,, atd.).

Objekt je vytvořen ze dvou zdrojů: podkategorie jeho verzí (třídy) a soubory zpráv (zprávy).

K dispozici je také MessageCache class (třída mezipaměti zpráv), který zpracovává zadávání textu prostřednictvím jmenného prostoru MediaWiki. Většina internacionalizace se v současnosti provádí prostřednictvím objektů a pomocí funkce zkratky , která je definována v. Starší kód může stále používat staré funkce, které jsou nyní považovány za zastaralé ve prospěch výše uvedených objektů Message.

Obecné použití (pro vývojáře)
Viz též.

Jazykové objekty
Existují dva způsoby, jak získat jazykový objekt. Globály a  můžete použít pro uživatelské rozhraní a jazyk obsahu. Pro libovolný jazyk můžete vytvořit objekt pomocí, nahrazením označení " " kódem jazyka například "cs". Můžete také použít, pokud   již může být jazykovým objektem. Seznam kódů je v.

Objekty Language jsou potřebné pro provádění funkcí specifických pro jazyk. Nejčastěji pro formátování čísla, času a data. Ale také pro vytváření seznamů a dalších věcí. Existuje několik způsobů ukládání do mezipaměti a sloučení s, ale podrobnosti jsou při běžném použití irelevantní.

Používání zpráv
MediaWiki používá „centrální“ úložiště zpráv, na která jsou v kódu odkazovány klíče. To se liší od například, který pouze extrahuje překladatelné řetězce ze zdrojových souborů. Systém založený na klíči usnadňuje některá řešení, jako jsou rafinace původních textů a sledování změn zpráv. Nevýhodou je samozřejmě to, že seznam použitých zpráv a seznam zdrojových textů pro tyto klíče se mohou synchronizovat. V praxi to není velký problém a jediným významným problémem je, že někdy i další zprávy, které se již nepoužívají, stále zůstanou na překlad.

Chcete-li, aby klíče zpráv byly lépe ovladatelné a snadno vyhledatelné, také s grifem, vždy je pište úplné a nespoléhejte se na jejich dynamické vytváření. Části klíčů zpráv můžete zřetězit, pokud máte pocit, že je to lepší pro vaší struktuřu, ale umístěte komentář se seznamem možných výsledných klíčů poblíž. Například:

Podrobné použití funkcí zpráv v PHP a JavaScript je na.

Přidávání nových zpráv
Viz též:

Výběr klíče zprávy
Viz též:

Klíč zprávy musí být celosvětově jedinečný. To zahrnuje jádro MediaWiki a všechna rozšíření a vzhledy.

Držte se malých písmen, číslic a pomlček v názvech zpráv; většina ostatních znaků je nepraktická nebo vůbec nefungují. Podle konvence MediaWiki na prvním znaku nerozlišuje velká a malá písmena a na ostatních znacích velká a malá písmena rozlišuje.

Při pojmenování postupujte podle globálních nebo místních konvencí. Pro rozšíření použijte standardní předponu, nejlépe název přípony, někdy následovaný spojovníkem ("-"). Výjimky:


 * Zprávy používané API. Musí začínat,  ,  . Za tuto předponu vložte příponu. (Tyto zprávy by měly být v samostatném souboru, obvykle pod i18 / api.)
 * Zprávy související s protokolem. Musí začínat,  ,.
 * Uživatelská práva. Klíč pro jméno práva uvedený na Special:ListGroupRights musí začínat na . Název akce, která dokončuje větu „“, musí začínat na
 * Značky revizí musí začínat.
 * Názvy speciálních stránek musí začínat.

Další informace, které byste si měli všimnout při vytváření zpráv

 * 1) Ujistěte se, že pro zprávu používáte vhodné zpracování (analýza,   nahrazení, vazbu na HTML atd.)
 * 2) Pokud je vaše zpráva součástí jádra, měla by být obvykle přidána k , ačkoli některé komponenty, jako jsou Installer, EXIF tagy a ApiHelp, mají své vlastní soubory zpráv.
 * 3) Pokud je vaše zpráva s příponou, přidejte ji do souboru   nebo do souboru   v příslušném podadresáři. Zejména zprávy API, které vidí pouze vývojáři, a nikoli většina koncových uživatelů, jsou obvykle v samostatném souboru, například  . Pokud rozšíření obsahuje mnoho zpráv, můžete vytvořit podadresáře pod  . Všechny adresáře zpráv, včetně výchozího , musí být uvedeny v sekci   v   nebo v proměnné.
 * 4) Dejte si pauzu a zvažte znění zprávy. Je vám to co nejjasnější? Nepochopili jste? Pokud je to možné, požádejte o připomínky od jiných vývojářů nebo lokalizátorů. Postupujte podle  #internacionalizace.
 * 5) Přidat dokumentaci na   ve stejném adresáři. Další informace ve  zprávě k dokumentaci.

Zprávy, které by neměly být překládány

 * 1) Ignorované zprávy jsou ty, které by měly existovat pouze v anglickém souboru zpráv. Jsou to zprávy, které by neměly potřebovat překlad, protože odkazují pouze na jiné zprávy nebo jazykově neutrální funkce, např. Na zprávu „ “.
 * 2) Volitelné zprávy mohou být přeloženy, pouze pokud byly změněny v cílovém jazyce.

Chcete-li takové zprávy nahlásit:


 * (volitelně) použijte šablonu v dokumentaci, to znamená
 * nebo
 * (požadováno) sdělte rozšíření použité na, co dělat se zprávami, odesláním opravy, která je uvede podle potřeby (viz také ):
 * pro jádro, v přidejte klíče zpráv
 * pod  nebo
 * pod ;
 * pro rozšíření, do přidejte řádek pod název rozšíření jako
 * or
 * or

Odstraňování existujících zpráv
Odstraňte ji z  a. Neobtěžujte se s jinými jazyky. Aktualizace od budou toto zpracovávat automaticky.

Změna existujících zpráv

 * 1) Zvažte aktualizaci dokumentace ke zprávě (viz  #Přidávání nových zpráv (#Adding new messages)).
 * 2) Změňte klíč zprávy, pokud staré překlady nejsou vhodné pro nový význam. To také zahrnuje změny v zacházení se zprávami (analýza, unikání, parametry atd.). Zlepšení formulace zprávy bez technických změn obvykle není důvodem pro změnu klíče. Na translatewiki.net budou překlady označeny jako zastaralé, aby na ně mohli překladatelé zacílit. Změna klíče zprávy nevyžaduje rozhovor s týmem i18n ani podání žádosti o podporu. Pokud však máte zvláštní okolnosti nebo otázky, zeptejte se na [Irc://irc.freenode.org/mediawiki-i18n #mediawiki-i18n] nebo na stránka podpory na.
 * 3) Pokud je rozšíření podporováno, změňte prosím pouze anglickou zdrojovou zprávu a / nebo klíč a doprovodnou položku v  . V případě potřeby se tým translatewiki.net postará o aktualizaci překladů, jejich označení jako zastaralých, vyčištění souboru nebo přejmenování klíčů, pokud je to možné. This also applies when you're only changing things like HTML tags which you could change in other languages without speaking those languages. Většina z těchto akcí se bude provede za translatewiki.net a dosáhne Gitu přibližně s jedním dnem zpoždění.

Lokalizace jmenných prostorů a aliasy speciálních stránek
a speciální názvy stránek (tj. "RecentChanges" v "Special:RecentChanges") jsou také přeložitelné.

Jmenné prostory


V současné době je překlad jmenného prostoru zakázán na translatewiki.net, takže to musíte udělat sami v Gerritu, nebo zadejte úkol s žádostí, aby to udělal někdo jiný.

Chcete-li povolit překlad vlastních jmenných prostorů představených vaší příponou, vytvořte soubor, který vypadá takto:

Poté načtěte překladový soubor oboru názvů do  až

Nyní, když uživatel nainstaluje MyExtension na finskou (fi) wiki, bude vlastní jmenný prostor automaticky přeložen do finštiny a uživatel nemusí nic dělat!

Nezapomeňte také zaregistrovat jmenný prostor (-y) vaší přípony na stránce.

Aliasy speciálních stránek
Aktuální informace naleznete v. Následující se nezdá být platným.

Vytvořte nový soubor pro aliasy speciálních stránek v tomto formátu:

Potom jej nahrajte do instalačního souboru rozšíření takto:

Pokud váš speciální kód stránky používá buď  nebo   (ve třídě, která poskytuje Special:MyExtension), použijte, pokud je k dispozici, lokalizovaný alias.

Parametry zprávy
Některé zprávy mají parametry. Jsou reprezentovány,  ,  , … ve (statických) textech zpráv a nahrazeny za běhu. Typické hodnoty parametrů jsou čísla („3“ v „Smazat 3 verze?“) nebo uživatelská jména („Bob“ na „Stránka naposledy editovaná Bobem“), názvy stránek, odkazy atd. Nebo někdy i jiné zprávy. Mohou mít libovolnou složitost.

Seznam parametrů definovaných pro každou konkrétní zprávu je umístěn ve speciálním souboru „qqq.json“, který je umístěn ve složce „languages/“ na MediaWiki - více v dokumentace.

Nejlepe je používat celá slova s magickými slovy PLURAL, GENDER a GRAMMAR. Například  je lepší než. Usnadňuje vyhledávání.

Přepínače ve zprávách ...

 * Viz také .

Hodnoty parametrů někdy ovlivňují přesná znění nebo gramatické variace ve zprávách. Neusilujeme o nepěkné konstrukce, jako je „$1 (sub)page(s) of his/her userpage“. Jsou pro uživatele špatné a můžeme je udělat lépe. Místo toho provedeme přepínače, které jsou analyzovány podle hodnot, které budou známy za běhu. Text statické zprávy pak poskytuje každou z možných voleb v seznamu, před níž je uveden název přepínače a odkaz na hodnotu, která se mění.

To se podobá způsobu, jakým se v MediaWiki nazývají (sparser funkce). K dispozici je několik typů přepínačů. Pracují pouze tehdy, pokud pro zprávy provádíte úplnou analýzu nebo -transformaci.

… na číslech prostřednictvím PLURALu

 * Viz také .

MediaWiki podporuje množné číslo, což vytváří hezčí vzhled produktu. Například:

Je-li pro konkrétní číslo uvedeno jednoznačně množné číslo, je možné s následující syntaxí

Buďte si vědomi použití PLURALUu u všech čísel

 * Viz též: Plural

Pokud je třeba do textu zprávy vložit číslo, uvědomte si, že některé jazyky budou muset použít PLURALu, i když jsou vždy větší než 1. Důvodem je, že v PLURALu v jiných jazycích než v angličtině jsou velmi odlišná a složitá rozlišení, srovnatelná s angličtinou 1st, 2nd, 3rd, 4th, … 11th, 12th, 13th, … 21st, 22nd, 23rd, … atd.

Nepokoušejte se dodávat tři různé zprávy pro případy jako „žádné položky se nepočítají“, „jedna položka se počítá“, „počítá se více položek“. Spíše nechte jednu zprávu, aby je všechny vzala. Nechte to na překladatelích a PLURALu, aby s nimi řádně zacházeli s případnými rozdíly v prezentaci v jejich příslušných jazycích.

Pokud je to možné, vždy uveďte číslo jako parametr. Pokud je to možné, vždy ke zdrojovým zprávám přidejte syntaxi. I když to v angličtině nemá smysl. Syntaxe řídí překladatele.

Jsou podporována zlomková čísla, ale množná pravidla nemusí být úplná.

Předejte počet položek seznamu jako parametry zprávám o seznamech
Nepředpokládejte, že existuje pouze singulární a množné číslo. Mnoho jazyků má více než dvě formy, které závisí na aktuálním použitém počtu a při vyjádření toho, co je uvedeno v seznamu viditelném pro čtenáře, musí použít gramatiku měnící se podle počtu položek v seznamu. Tedy, když váš kód vypočítá seznam, zahrňte  jako parametr do titulků, náběhů, zápatí a dalších zpráv o seznamu, i když se počet v angličtině nepoužívá. Existuje neutrální způsob, jak mluvit o neviditelných seznamech, takže můžete mít odkazy na seznamy na dalších stránkách, aniž byste museli předem počítat položky.

… o uživatelských jménech prostřednictvím GENDER

 * Viz také .

Pokud se ve zprávě odkazujete na uživatele, předejte do zprávy uživatelské jméno jako parametr a do dokumentace zprávy přidejte zmínku o tom, že je podporováno pohlaví. Pokud je pravděpodobné, že GENDER bude použito v překladech do jazyků s genderovým skloňováním, přidejte je explicitně do zdrojové zprávy v anglickém jazyce.

Pokud přímo oslovujete aktuálně přihlášeného uživatele, nechte uživatelské jméno jako parametr prázdné:

Pokud do zprávy zahrnete uživatelské jméno (např. „“), zvažte nejprve jeho předání prostřednictvím, abyste zajistili, že znaky jako   nebo   nebudou interpretovány.

Uživatelé mají gramatická pohlaví

 * Viz též Gender

Když zpráva hovoří o uživateli, nebo se týká uživatele, nebo oslovuje uživatele přímo, uživatelské jméno by mělo být předáno zprávě jako parametr. Jazyky, které musejí nebo chtějí používat správnou gramatiku závislou na pohlaví, tak mohou udělat. To by mělo být provedeno, i když se uživatelské jméno nemá ve zprávě zobrazovat, například v „informujte uživatele na své diskusní stránce“, což je lépe provedeno „informujte uživatele na diskusní stránce “také v angličtině.

To neznamená, že jste vyzváni, abyste „sexizovali“ jazyk zpráv: používejte rodově neutrální jazyk, kdykoli je to možné s jasností a přesností.

… o použití kontextu uvnitř vět pomocí GRAMMAR

 * Viz také .

K dispozici jsou také gramatické transformace pro aglutinační jazyky. Například pro finštinu, kde bylo naprosto nutné učinit jazykové soubory nezávislými na webu, tj. odebrat odkazy z Wikipedie. Ve finštině se „about Wikipedia“ stává „Tietoja Wikipediasta“ a „you can upload it to Wikipedia“ se stává „Voit tallentaa tiedoston Wikipediaan“. Přípony se přidávají v závislosti na tom, jak se slovo používá spolu s drobnými úpravami základu. Existuje dlouhý seznam výjimek, ale protože bylo potřeba přeložit pouze několik slov, jako je název webu, nemuseli jsme jej uvádět.

MediaWiki má gramatické transformační funkce pro více než 20 jazyků. Některé z nich jsou pouze slovníky pro názvy webů Wikimedia, ale jiné mají jednoduché algoritmy, které ale selžou ve všech nejběžnějších případech.

Ještě předtím, než MediaWiki provedla libovolnou gramatickou transformaci, měla pro názvy měsíců nominativní (v prvním pádu) / genitivní (pádové) rozlišení. Toto rozlišení je nutné u některých jazyků, pokud chcete nahradit názvy měsíců větami.

Filtrování speciálních znaků v parametrech a ve zprávách
Dalším (mnohem jednodušším) problémem se substitucí parametrů je únik HTML. Přestože je MediaWiki mnohem jednodušší, dělá to docela špatně.

Dokumentace zprávy
Pro dokumentaci zpráv se používá pseudojazykový kód. Je to jeden z kódů standardu ISO 639, vyhrazený pro speciální použití. Tam neudržujeme překlady každé zprávy, ale shromažďujeme anglické věty „o každé zprávě“. Sděluje nám, kde se používá, poskytujeme rady o tom, jak ji překládat, a vyjmenovávat a popisovat její parametry, odkaz na související zprávy, a tak dále. V translatewiki.net se tyto rady zobrazují překladatelům, když upravují zprávy.

Programmers must document each and every message. Message documentation is an essential resource – not just for translators, but for all the maintainers of the module. Whenever a message is added to the software, a corresponding  entry must be added as well; revisions which don't do so are marked " " until the documentation is added.

Documentation in  files should be edited directly only when adding new messages or when changing an existing English message in a way that requires a documentation change, for example adding or removing parameters. In other cases, documentation should usually be edited in translatewiki. Each documentation string is accessible at https://translatewiki.net/wiki/MediaWiki: message-key /qqq, as if it were a translation. These edits will be exported to the source repositories along with the translations.

Useful information that should be in the documentation includes:
 * 1) Message handling (parsing, escaping, plain text).
 * 2) Type of parameters with example values.
 * 3) Where the message is used (pages, locations in the user interface).
 * 4) How the message is used where it is used (a page title, button text, etc.).
 * 5) What other messages are used together with this message, or which other messages this message refers to.
 * 6) Anything else that could be understood when the message is seen on the context, but not when the message is displayed alone (which is the case when it is being translated).
 * 7) If applicable, notes about grammar. For example, "open" in English can be both a verb and an adjective. In many other languages the words are different and it's impossible to guess how to translate them without documentation.
 * 8) Adjectives that describe things, such as "disabled", "open" or "blocked", must always say what are they describing. In many languages adjectives must have the gender of the noun that they describe. It may also happen that different kinds of things need different adjectives.
 * 9) If the message has special properties, for example, if it is a page name, or if it should not be a direct translation, but adapted to the culture or the project.
 * 10) Whether the message appears near other message, for example in a list or a menu. The wording or the grammatical features of the words should probably be similar to the messages nearby. Also, items in a list may have to be properly related to the heading of the list.
 * 11) Parts of the message that must not be translated, such as generic namespace names, URLs or tags.
 * 12) Explanations of potentially unclear words, for example abbreviations, like "CTA", or specific jargon, like "template", "suppress" or "stub". (Note that it's best to avoid such words in the first place!)
 * 13) Screenshots are very helpful. Don't crop – an image of the full screen in which the message appears gives complete context and can be reused in several messages.

A few other hints:
 * Remember that very, very often translators translate the messages without actually using the software.
 * Most usually, translators do not have any context information, neither of your module, nor of other messages in it.
 * A rephrased message alone is useless in most circumstances.
 * Don't use designers' jargon like "nav" or "comps".
 * Consider writing a glossary of the technical terms that are used in your module. If you do it, link to it from the messages.

You can link to other messages by using. Please do this if parts of the messages come from other messages (if this cannot be avoided), or if some messages are shown together or in same context.

translatewiki.net provides some default templates for documentation: Have a look at the template pages for more information.
 * for  messages
 * for  messages
 * for messages around user groups (, ,  ,   and  )
 * for  messages

Internationalisation hints
Besides documentation, translators ask to consider some hints so as to make their work easier and more efficient and to allow an actual and good localisation for all languages. Even if only adding or editing messages in English, one should be aware of the needs of all languages. Each message is translated into more than 300 languages and this should be done in the best possible way. Correct implementation of these hints will very often help you write better messages in English, too.

These are the main places where you can find the assistance of experienced and knowledgeable people regarding i18n:
 * The support page of translatewiki.net.
 * The #mediawiki-i18n irc channel on http://freenode.net.

Please do ask there!

Use Message parameters and switches properly
That's a prerequisite of a correct wording for your messages.

Avoid message re-use
The translators discourage message re-use. This may seem counter-intuitive, because copying and duplicating code is usually a bad practice, but in system messages it is often needed. Although two concepts can be expressed with the same word in English, this doesn't necessarily mean they can be expressed with the same word in every language. "OK" is a good example: in English this is used for a generic button label, but in some languages they prefer to use a button label related to the operation which will be performed by the button. Another example is practically any adjective: a word like "multiple" changes according to gender in many languages, so you cannot reuse it to describe several different things, and you must create several separate messages.

If you are adding multiple identical messages, please add message documentation to describe the differences in their contexts. Don't worry about the extra work for translators. Translation memory helps a lot in these while keeping the flexibility to have different translations if needed.

Avoid fragmented or 'patchwork' messages
Languages have varying word orders, and complex grammatical and syntactic rules. It's very hard to translate "lego" messages, that is messages formed by multiple pieces of text, possibly with some indirection (also called "string concatenation").

It is better to make every message a complete phrase. Several sentences can usually be combined much more easily into a text block, if needed. When you want to combine several strings in one message, pass them in as parameters, as translators can order them correctly for their language when translating.

Messages quoting each other
An exception from the rule may be messages referring to one another: 'Enter the original author's name in the field labelled " " and click "  " when done'. This makes the message consistent when a software developer or wiki operator alters the messages "name" or "proceed" later. Without the int-hack, developers and operators would have to be aware of all related messages needing adjustment, when they alter one.

Don't use terms and templates that are specific to particular projects
MediaWiki is used by very diverse people, within the Wikimedia movement and outside of it. Even though it was originally built for an encyclopedia, it is now used for various kinds of content. Therefore, use general terms. For example, avoid terms like "article", and use "page" instead, unless you are absolutely sure that the feature you are developing will only be used on a site where pages are called "articles". Don't use "village pump", which is the name of an English Wikipedia community page, and use a generic term, such as "community discussion page", instead.

Don't assume that a certain template exists on all wikis. Templates are local to wikis. This applies to both the source messages and to their translations. If messages use templates, they will only work if a template is created on each wiki where the feature is deployed. It's best to avoid using templates in messages completely. If you really have to use them, you must document this clearly in the message documentation and in the extension installation instructions.

Separate times from dates in sentences
Some languages have to insert something between a date and a time which grammatically depends on other words in a sentence. Thus, they will not be able to use date/time combined. Others may find the combination convenient, thus it is usually the best choice to supply three parameter values (date/time, date, time) in such cases, and in each translation leave either the first one or last two unused as needed.

Avoid in messages
has several disadvantages. It can be anything (acronym, word, short phrase, etc.) and, depending on language, may need the use of  on each occurrence. No matter what, each message having  will need review in most wiki languages for each new wiki on which your code is installed. In the majority of cases, when there is not a general  configuration for a language, wiki operators will have to add or amend PHP code so as to get   for   working. This requires both more skills, and more understanding, than otherwise. It is more convenient to have generic references like "this wiki". This does not keep installations from locally altering these messages to use, but at least they don't have to, and they can postpone message adaption until the wiki is already running and used.

Avoid references to visual layout and positions
What is rendered where depends on skins. Most often screen layouts of languages written from left-to-right are mirrored compared to those used for languages written from right-to-left, but not always, and for some languages and wikis, not entirely. Handheld devices, narrow windows, and so on may show blocks underneath each other, that would appear side-by-side on larger displays. Since site- and user-written JavaScript scripts and gadgets can, and do, hide parts, or move things around in unpredictable ways, there is no reliable way of knowing the actual layout.

It is wrong to tie layout information to content languages, since the user interface language may not be the page's content language, and layout may be a mixture of the two depending on circumstances. Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of visual layout. Thus, you should not refer to visual layout positions in the majority of cases, though semantic layout terms may still be used ("previous steps in the form", etc.).

MediaWiki does not support showing different messages or message fragments based on the current directionality of the interface (see T30997).

The upcoming browser and MediaWiki support for East and North Asian top-down writing will make screen layouts even more unpredictable, with at least eight possible layouts (left/right starting position, top/bottom starting position, and which happens first).

Avoid references to screen colours
The colour in which something is rendered depends on many factors, including skins, site- and user-written JavaScript scripts and gadgets, and local user agent over-rides for reasons of accessibility or technological limitations. Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of colour. Thus, you should not refer to screen colours. (You should also not rely on colour alone as a mechanism for informing the user of state, for the same reason.)

Have message elements before and after each input field

 * This is a suggested guideline, has not become standard in MediaWiki development

While English allows efficient use of prompting in the form item–colon–space–input-field, many other languages don't. Even in English, you often want to use "Distance: ___ metres" rather than "Distance (in metres): ___". Leaving  elements aside, you should think of each and every input field following the "Distance: ___ metres" pattern. So:
 * give it two messages, even if the 2nd one is empty in English and some other languages, or
 * allow the placement of inputs via  parameters.

Avoid untranslated HTML markup in messages
HTML markup not requiring translation, such as enclosing s, rulers above or below, and similar, should usually not be part of messages. They unnecessarily burden translators, increase message file size, and pose the risk to accidentally being altered or skipped in the translation process. In general, avoid raw HTML in messages if you can.

Messages are often longer than you think!
Skimming foreign language message files, you find messages almost never shorter than Chinese ones, rarely shorter than English ones, and most usually much longer than English ones.

Especially in forms, in front of input fields, English messages tend to be terse, and short. That is often not kept in translations. Especially genuinely non-technical third world languages, vernacular, mediæval, or ancient languages require multiple words or even complete sentences to explain foreign, or technical, prompts. For example, the brief English message "TSV file:" may have to be translated in a language as literally:"Please type a name here which denotes a collection of computer data that is comprised of a sequentially organised series of typewritten lines which themselves are organised as a series of informational fields each, where said fields of information are fenced, and the fences between them are single signs of the kind that slips a typewriter carriage forward to the next predefined position each. Here we go: _____ (thank you)" This is, admittedly, an extreme example, but you get the trait. Imagine this sentence in a column in a form where each word occupies a line of its own, and the input field is vertically centered in the next column. :-(

Avoid using very close, similar, or identical words to denote different things, or concepts
For example, pages may have older revisions (of a specific date, time, and edit), comprising past versions of said page. The words revision, and version can be used interchangeably. A problem arises, when versioned pages are revised, and the revision, i.e. the process of revising them, is being mentioned, too. This may not pose a serious problem when the two synonyms of "revision" have different translations. Do not rely on that, however. It is better to avoid the use of "revision" aka "version" altogether, then, so as to avoid it being mis-interpreted.

Basic words may have unforeseen connotations, or not exist at all
There are some words that are hard to translate because of their very specific use in MediaWiki. Some may not be translated at all. For example, there is no word "user" relating to "someone who uses something" in several languages. Similarly, in Kölsch the English words "namespace" and "apartment" translate the same word. Sticking to Kölsch, they say "corroborator and participant" in one word since any reference to "use" would too strongly imply "abuse" as well. The term "wiki farm" is translated as "stable full of wikis", since a single-crop farm would be a contradiction in terms in the language, and not understood, etc..

Expect untranslated words

 * This is a suggested guideline, has not yet become standard in MediaWiki development

It is not uncommon that proper names, tag names, etc. and computerese in English are not translated, and instead taken as loan-words, or foreign words. In the latter case, some particularly-fastidious translators may mark such words as belonging to another language with HTML markup, such as  ….

You may want to consider ensuring that your message output handler passes such markup along unmolested, despite the obvious security risks.

Permit explanatory inline markup

 * This is a suggested guideline, has not yet become standard in MediaWiki development

Sometimes there are abbreviations, technical terms, or generally ambiguous words in target languages that may not be immediately understood by newcomers, but are obvious to experienced computer users. So as to avoid screen clutter of lengthy explanations without leaving newcomers stranded, translators may choose to add explanations as  annotations, shown by browsers when you move the mouse over them.

For example, the MediaWiki core message  about image rotation, which in English is simply " ", in Moroccan Arabic is translated as:

giving:
 * mḍwwer 90° ĜĜS

explaining the abbreviation for "counter clockwise" when needed.

You may want to consider ensuring that your message output handler passes such markup along unmolested, even if the original message does not use them.

Use, , and tags where needed
When talking about technical parameters, values, or keyboard inputs, mark them appropriately as such using the HTML tags,  , or. Thus they are typographically set off form the normal text. That clarifies their sense to readers, avoiding confusion, errors and mis-representations. Ensure that your message handler allows such markup.

Symbols, colons, brackets, etc. are parts of messages
Many symbols are localisable, too. Some scripts have other kinds of brackets than the Latin script has. A colon may not be appropriate after a label or input prompt in some languages. Having those symbols included in messages helps to make better and less Anglo-centric translations, and also reduces code clutter.

For example, there are different quotation mark conventions used in «Norwegian», »Swedish», »Danish«, „German“, and 「Japanese」.

If you need to wrap some text in localized parentheses, brackets, or quotation marks, you can use the   or    or    messages like so:

Do not expect symbols and punctuation to survive translation
Languages written from right to left (as opposed to English) usually swap arrow symbols being presented with "next" and "previous" links, and their placement relative to a message text may, or may not, be inverted as well. Ellipsis may be translated to "etc.", or to words. Question marks, exclamation marks, colons will be placed other than at the end of a sentence, not at all, or twice. As a consequence, always include all of those in the text of your messages, and never try to insert them programmatically.

Use full stops
Do terminate normal sentences with full stops. This is often the only indicator for a translator to know that they are not headlines or list items, which may need to be translated differently.

Wikitext of links
Link anchors can be put into messages in several technical ways:
 * 1) via wikitext: …   …,
 * 2) via wikitext: …  …, or
 * 3) the anchor text is a message in the MediaWiki namespace. Avoid it!

The latter is often hard or impossible to handle for translators, avoid fragmented or 'patchwork' messages here, too. Make sure that " " does not contain spaces.

Use meaningful link anchors
Take care with your wording. Link anchors play an important role in search engine assessment of pages – both the words linked, and the target anchor. Make sure that the anchor describes the target page well. Always avoid commonplace and generic words. For example, "Click here" is an absolute no-go, since target pages are almost never about "click here". Do not put that in sentences around links either, because "here" was not the place to click. Instead, Use precise action words telling what a user will get to when following the link, such as "You can upload a file if you wish."

See also Help users predict where they are going and mystery meat navigation.

Avoid jargon and slang
Avoid developer and power user jargon in messages. Try to use a simple language whenever possible. Avoid saying "success", "successfully", "fail", "error occurred while", etc., when you want to notify the user that something happened or didn't happen. This comes from developers' seeing everything as true or false, but users usually just want to know what actually happened or didn't, and what they should do about it (if at all). So:
 * "The file was successfully renamed" -> "The file was renamed"
 * "File renaming failed" -> "There is a file with this name already. Please choose a different name."

One sentence per line

 * This is a suggested guideline, has not yet become standard in MediaWiki development

Try to have one sentence or similar block in one line. This helps to compare the messages in different languages, and may be used as an hint for segmentation and alignment in translation memories.

Be aware of whitespace and line breaks
MediaWiki's localised messages usually get edited within the wiki, either by wiki operations on live wikis, or by the translators on translatewiki.net. You should be aware of how whitespace, especially at the beginning or end of your message, will affect editors:


 * Newlines at the beginning or end of a message are fragile, and will be frequently removed by accident. Start and end your message with active text; if you need a newline or paragraph break around it, your surrounding code should deal with adding it to the returned text.
 * Spaces at the beginning or end of a message are also likely to be removed during editing, and should be avoided. If a space is required for output, usually your code should append it or else you should use a non-breaking space such as &amp;nbsp; (in which case check your escaping settings!)

Use standard capitalisation
Capitalisation gives hints to translators as to what they are translating, such as single words, list or menu items, phrases, or full sentences. Correct (standard) capitalisation may also play a role in search engines' assessment of your pages. MediaWiki uses sentence case (The quick brown fox jumps over the lazy dog) in interface messages.

Always remember that many writing systems don't have capital letters at all, and some of those that do have them, use them differently from English. Therefore, don't use ALL-CAPS for emphasis. Use CSS, or HTML  or   per below:

Emphasis
In normal text, emphasis like boldface or italics and similar should be part of message texts. Local conventions on emphasis often vary, especially some Asian scripts have their own. Translators must be able to adjust emphasis to their target languages and areas. Try to use " " and " " in your user interface to allow mark-up on a per language or per script basis.

In modern screen layouts of English and European styles, emphasis becomes less used. Do convey it in your message documentation still, as it may give valuable hints as to how to translate. Emphasis can and should be used in other cultural contexts as appropriate, provided that translators know about it.

Aktualizace lokalizace
As mentioned above, translation happens on translatewiki.net and other systems are discouraged. Here's a high level overview of the localisation update workflow:
 * Developers.
 * Users translate the new or changed system messages on translatewiki.net.
 * Automated tools export these messages, build new versions of the message files, incorporating the added or updated messages, for both core and extensions, and commit them to git.
 * The wikis then can pull in the updated system messages from the git repository.

Wikimedia projects and any other wikis can benefit immediately and automatically from localisation work thanks to the extension. This compares the latest English messages to the English messages in production. If they are not the same, the production translations are updated and made available to users.

Once translations are in the version control system, the Wikimedia Foundation has a daily job that updates a checkout or clone of the extension repository. This was first established in September 2009.

Because changes on translatewiki.net are pushed to the code daily as well, this means that each change to a message can potentially be applied to all existing MediaWiki installations in a couple days without any manual intervention or traumatic code update.

As you can see this is a multi-step process. Over time, we have found out that many things can go wrong. If you think the process is broken, please make sure to report it on our Support page, or create a new bug in Phabricator. Always be sure to describe a precise observation.

Handling support requests

 * Main page: translatewiki:Translating:Localisation for developers.

Translators may have questions about some of the messages you create. Translatewiki.net provides a support request system that allows translators the ability to ask you, the project owner, questions regarding messages so that they can be better translated. This short tutorial guides you through the workflow of handling translatewiki.net support requests.

Message sources
Code looks up from these sources:


 * The MediaWiki namespace. This allows wikis to adopt, or override, all of their messages, when standard messages do not fit or are not desired (see #Old local translation system).
 * MediaWiki:Message-key is the default message,
 * MediaWiki:Message-key/language-code is the message to be used when a user has selected a language other than the wiki's default language.
 * From message files:
 * Core MediaWiki itself and most currently maintained extensions use a file per language, named, where zyx is the language code for the language.
 * Some older extensions use a combined message file holding all messages in all languages, usually named.
 * Many Wikimedia Foundation wikis access some messages from the extension, allowing them to standardise messages across WMF wikis without imposing them on every MediaWiki installation.
 * A few extensions use other techniques.

Caching
System messages are one of the more significant components of MediaWiki, primarily because it is used in every web request. The PHP message files are large, since they store thousands of message keys and values. Loading this file (and possibly multiple files, if the user's language is different from the content language) has a large memory and performance cost. An aggressive, layered caching system is used to reduce this performance impact.

MediaWiki has lots of caching mechanisms built in, which make the code somewhat more difficult to understand. Since 1.16 there is a new caching system, which caches messages either in. files or in the database. Customised messages are cached in the filesystem and in (or alternative), depending on the configuration.

The table below gives an overview of the settings involved:

In MediaWiki 1.27.0 and 1.27.1, the autodetection was changed to favor the file backend. In case  (the default), the file backend is used with the path from. If this value is not set (which is the default), a temporary directory determined by the operating system is used. If a temporary directory cannot be detected, the database backend is used as a fallback. This was reverted from 1.27.2 and 1.28.0 because of conflict of files on shared hosts and security issues (see T127127 and T161453).

Function backtrace
To better visually depict the layers of caching, here is a function backtrace of what methods are called when retrieving a message. See the below sections for an explanation of each layer.

MessageCache
The  class is the top level of caching for messages. It is called from the Message class and returns the final raw contents of a message. This layer handles the following logic: The last bullet is important. allow MediaWiki to fall back on another language if the original does not have a message being asked for. As mentioned in the next section, most of the language fallback resolution occurs at a lower level. However, only the  layer checks the database for overridden messages. Thus integrating overridden messages from the database into the fallback chain is done here. If not using the database, this entire layer can be disabled.
 * Checking for message overrides in the database
 * Caching over-ridden messages in, or whatever is set to
 * Resolving the remainder of the sequence

LocalisationCache
See

LCStore
The  class is merely a back-end implementation used by the LocalisationCache class for actually caching and retrieving messages. Like the  class, which is used for general caching in MediaWiki, there are a number of different cache types (configured using ): The "file" option is used by the Wikimedia Foundation, and is recommended because it is faster than going to the database and more reliable than the APC cache, especially since APC is incompatible with PHP versions 5.5 or later.
 * "db" (default) - Caches messages in the database
 * "file" (default if  is set) - Uses CDB to cache messages in a local file
 * "accel" - Uses APC or another opcode cache to store the data

Licence
Any edits made to the language must be licensed under the terms of the GNU General Public License to be included in the MediaWiki software. Other extensions may be under different licences.

Old local translation system
With MediaWiki 1.3.0, a new system was set up for localising MediaWiki. Instead of editing the language file and asking developers to apply the change, users could edit the interface strings directly from their wikis. This is the system in use as of August 2005. People can find the message they want to translate in Special:AllMessages and then edit the relevant string in the  namespace. Once edited, these changes are live. There was no more need to request an update, and wait for developers to check and update the file.

The system is great for Wikipedia projects; however a side effect is that the MediaWiki language files shipped with the software are no longer quite up-to-date, and it is harder for developers to keep the files on meta in sync with the real language files.

As the default language files do not provide enough translated material, we face two problems:
 * 1) New Wikimedia projects created in a language which has not been updated for a long time, need a total re-translation of the interface.
 * 2) Other users of MediaWiki (including Wikimedia projects in the same language) are left with untranslated interfaces. This is especially unfortunate for the smaller languages which don't have many translators.

This is not such a big issue anymore, because translatewiki.net is advertised prominently and used by almost all translations. Local translations still do happen sometimes but they're strongly discouraged. Local messages mostly have to be deleted, moving the relevant translations to translatewiki.net and leaving on the wiki only the site-specific customisation; there's a huge backlog especially in older projects, [//toolserver.org/~robin/?tool=cleanuplocalmsgs this tool] helps with cleanup.

Keeping messages centralised and in sync
English messages are very rarely out of sync with the code. Experience has shown that it's convenient to have all the English messages in the same place. Revising the English text can be done without reference to the code, just like translation can. Programmers sometimes make very poor choices for the default text.

Co lze lokalizovat
So many things are localisable on MediaWiki that not all of them are directly available on translatewiki.net: see translatewiki:Translating:MediaWiki. If something requires a developer intervention on the code, you can request it on Phabricator, or ask at Support if you don't know what to do exactly.


 * Namespaces (both core and extensions', plus gender-dependent user namespaces)
 * Weekdays (and abbreviations)
 * Months (and abbreviations)
 * Bookstores for Special:BookSources
 * Skin names
 * Math names
 * (for compatibility with old MediaWiki databases)
 * Default user option overrides
 * Language names
 * Country names (via )
 * Currency names (via )
 * Timezones
 * Character encoding conversion via
 * UpperLowerCase first (needs casemaps for some)
 * UpperLowerCase
 * Uppercase words
 * Uppercase word breaks
 * Case folding
 * Strip punctuation for MySQL search (search optimisation)
 * Get first character
 * Alternate encoding
 * Recoding for edit (and then recode input)
 * Get first character
 * Alternate encoding
 * Recoding for edit (and then recode input)
 * Fallback languages (that is, other more closely related language(s) to use when a translation is not available, instead of the default fallback, which is English)
 * Directionality (left to right or right to left, RTL)
 * Direction mark character depending on RTL
 * Arrow depending on RTL
 * Languages where italics cannot be used
 * Number formatting (comma-ify, i.e. adding or not digits separators; transform digits; transform separators)
 * Truncate (multibyte)
 * Grammar conversions for inflected languages
 * Plural transformations
 * Formatting expiry times
 * Segmenting for diffs (Chinese)
 * Convert to variants of language (between different orthographies, or scripts)
 * Language specific user preference options
 * and link prefix, e.g.:  These are letters that can be glued after/before the closing/opening brackets of a wiki link, but appear rendered on the screen as if part of the link (that is, clickable and in the same colour). By default the link trail is "a-z"; you may want to add the accentuated or non-Latin letters used by your language to the list.
 * Language code (preferably used according to the latest RFC in standard BCP 47, currently RFC 5646, with its associated IANA database. Avoid deprecated, grandfathered and private-use codes: look at what they mean in standard ISO 639, and avoid codes assigned to collections/families of languages in ISO 639-5, and ISO 639 codes which were not imported in the IANA database for BCP 47)
 * Type of emphasising
 * The extension has a special page file per language,   for language code.

Neat functionality:


 * I18N
 * Roman numeral formatting

Namespace name aliases
Namespace name aliases are additional names which can be used to address existing namespaces. They are rarely needed, but not having them when they are, usually creates havoc in existing wikis.

You need namespace name aliases:


 * 1) When a language has variants, and these variants spell some namespaces differently, and you want editors to be able to use the variant spellings. Variants are selectable in the user preferences. Users always see their selected variant, except in wikitext, but when editing or searching, an arbitrary variant can be used.
 * 2) When an existing wiki's language, fall back language(s), or localisation is changed, with it are changed some namespace names. So as not to break the links already present in the wiki, that are using the old namespace names, you need to add each of the altered previous namespace names to its namespace name aliases, when, or before, the change is made.

The generic English namespace names are always present as namespace name aliases in all localisations, so you need not, and should not, add those.

Aliases can't be translated on translatewiki.net, but can be requested there or on bugzilla: see translatewiki:Translating:MediaWiki.

Regional settings
Some linguistic settings vary across geographies; MediaWiki doesn't have a concept of region, it only has languages and language variants.

These settings need to be set once as a language's default, then individual wikis can change them as they wish in their configuration.

Time and date formats
Time and dates are shown on special pages and alike. The default time and date format is used for signatures, so it should be the most used and most widely understood format for users of that language. Also anonymous users see the default format. Registered users can choose other formats in their preferences.

If you are familiar with PHP's time format, you can try to construct formats yourself. MediaWiki uses a similar format string, with some extra features. If you don't understand the previous sentence, that's OK. You can provide a list of examples for.

Old edit window toolbar buttons

 * Not to be confused with the much more common 's "advanced toolbar", which has similar features.

When a wiki page is being edited, and a user has allowed it in their Special:Preferences, a set of icons is displayed above the text area where one can edit. The toolbar buttons can be set but there are no messages for it. What we need is a set of properly sized  files. Plenty of samples can be found in commons:Category:ButtonToolbar, and there is an empty button image to start off from.

Missing
'''This section is missing about the changes in the i18n system related to extensions. The format was standardised and messages are automatically loaded.'''

See #Message sources.