Help:System message/cs

Systémová zpráva je úryvek prostého textu (nowiki), wikitext, CSS nebo JavaScript, který lze použít k přizpůsobení chování MediaWiki a jeho zobrazení pro každý jazyk a lokální počítačový software. MediaWiki používá zprávy pro jakoukoli část uživatelského rozhraní, což umožňuje internacionalizaci a lokalizaci uživatelského rozhraní MediaWiki pro jádro i rozšíření. Všechny zprávy používané v MediaWiki jsou definovány v souboru zpráv.

Přepisování zpráv na wiki
Zprávy lze přepsat z jejich výchozích hodnot úpravou na wiki. Každá zpráva má wiki stránku v oboru názvů MediaWiki s klíčem zprávy jako názvem stránky. Například zpráva "aboutsite" je uložena na MediaWiki:aboutsite. Ve výchozím nastavení je tento obor názvů omezen na úpravy, pokud uživatel nemá oprávnění "editinterface" (rozhraní pro úpravy). Seznam všech stránek se zprávami naleznete na Special:AllMessages. Úpravy zpráv rozhraní jsou obvykle jednoduché, stejně jako úpravy normální stránky wiki, ale jsou omezeny na uživatele s povolením editinterface, které je ve výchozím nastavení přiřazeno správcům (a správcům rozhraní). Speciální stránka Special:AllMessages vypisuje zvlášť pro každou zvolenou jazykovou mutaci tabulku se dvěma sloupci: název propojeného rozhraní a text. Text je vodorovně rozdělen, aby se zobrazil výchozí text nahoře a přizpůsobený text níže. Pokud vlastní zpráva neexistuje, zobrazí se pouze výchozí. Pokud chcete přizpůsobit zprávu, klikněte na horní odkaz v levém sloupci (název zprávy). Tento odkaz je červený, pokud se používá výchozí text, protože stránka pro úpravy je prázdná.

Druhý odkaz v levém sloupci vede na stránku, na které lze vést případnou diskuzi o tom jak má vypadat obsah příslušné zprávy.

Vyhledávání zpráv a dokumentace
Jak se v MediaWiki se zprávami pracuje, jaké jsou s nimi spojené proměnné, parametry, omezení atp. je popsáno v [//translatewiki.net/w/i.php?title=Special:Translate&task=reviewall&group=core&language=qqq&limit=5000&action=page&filter= dokumentaci k souborům pseudojazyka qqq], a v pravidlech pro dokumentaci zpráv. Pro některé starší zprávy můžete najít obsáhlejší dokumentaci v rámci původní.

Od MediaWiki verze 1.18 a vyšší, můžete vyhledat identifikační řetězce zpráv použitých na stránce jejím zobrazení s využitím kódu pseudo-jazyka. To lze udělat buď tak, že připojíte za URL příslušné wiki stránky, nebo pokud již URL obsahuje znak   přidáte parametr   (viz [ například]). Místo obsahu zprávy se tak na stránce zobrazí její identifikační řetězec (klíč), takže pak můžete snadno vyhledat ten, který odpovídá zprávě, kterou chcete upravit. Je-li zpráva součástí obsahu stránky, tak se při použití qqx nic nezobrazí.

Některé části rozhraní přidávají do řetězce, který se zobrazuje při použití triku qqx,. Například štítek na kartě, který odkazuje na diskusní stránku v hlavním jmenném prostoru, se zobrazuje jako, ale řetězec je ve skutečnosti umístěn v MediaWiki:Talk.

V případě, že stránka používá nějaké vlastní záložky jako např. speciální stránka "Nastavení" budete muset přidat záložku až za parametr, např. .

Formát lokalizačního souboru
Všechny zprávy používané v MediaWiki jsou definovány v souboru zpráv.

V MediaWiki existují dva typy souborů zpráv: JSON a PHP. Od dubna 2014 byla základní MediaWiki a většina udržovaných rozšíření migrována do formátu JSON. Pro veškerý nový vývoj byste měli používat JSON. Další informace o migraci na JSON najdete na stránce Requests for comment/Localisation format.

JSON
Od konce roku 2013 byl zaveden nový formát souborů pro zprávy: JSON. Toto je prostý JSON, známý jako běžný obecný formát ukládání dat. Každý klíč v něm je klíčem zprávy a hodnotou je text zprávy. Speciální klíč  navíc slouží k uložení informací o překladu, jako jsou autoři překladu.

Použitím JSON jsou lokalizační soubory bezpečnější, protože nejsou spustitelné. Je také kompatibilní s jquery.i18n, knihovnou JavaScript vyvinutou jako součást projektu Milkshake, která poskytuje možnosti lokalizace frontendu podobné MediaWiki a je používána některými rozšířeními, která chtějí být méně závislá na MediaWiki, jako je VisualEditor a UniversalLanguageSelector.

Protože širší sada nástrojů pro internacionalizaci a lokalizaci byla nazvána "Project Milkshake", někteří lidé nazývají tento formát "banán".

Umístění souboru
V jádru MediaWiki jsou lokalizační soubory umístěny v adresáři. Rozšíření MediaWiki obvykle umístí svá rozšíření do podadresáře. Pokud v rámci projektu existuje velký počet zpráv, je možné je rozdělit do dvou nebo více aktuálních podadresářů, aby bylo možné je udržovat. V kontextu MediaWiki se k výpisu těchto podadresářů používá konfigurační klíč. Zde je příklad z rozšíření VisualEditoru pro MediaWiki:

Nové zprávy přidáte do anglického souboru zpráv "en"  a zdokumentujete je v souboru dokumentace zpráv se speciálním kódem pseudojazyka "qqq" –. Viz také: Přidávání nových zpráv.

Metadata
V současné době se v souborech používají následující pole metadat:


 * authors
 * JSON seznam autorů zpráv. Pro angličtinu (en) a dokumentaci ke zprávám (qqq) jsou tyto při úpravě souboru zpráv přidány ručně. U všech ostatních jazyků se toto vkládá automaticky při exportu souboru zpráv z translatewiki.net. Dokumentaci zprávy lze upravovat na translatewiki.net a do souboru qqq.json se automaticky vkládají také editace dokumentace.


 * message-documentation
 * Toto je kód pseudojazyka pro ukládání dokumentace zprávy. Pro MediaWiki je to vždy qqq. (To se objevuje v některých rozšířeních, ale ve skutečnosti není žádným způsobem zpracováno. Není to povinné.)

Konvence
Speciální znaky, jako jsou zalomení řádků, jsou escapovány.

Znaky Unicode, které představují písmena v různých abecedách, jsou uloženy jako skutečné znaky a nikoli jako kódy znaků, protože tyto soubory někdy čtou lidé, a proto jsou soubory menší ( a ne  ). V každém případě mají vývojáři málo důvodů upravovat zprávy v jakémkoli jazyce kromě angličtiny, protože ty se obvykle upravují přes translatewiki.net.

Neunikne ani kód HTML, takže  a ne.

Soubory JSON jsou odsazeny pomocí tabulátorů.

PHP
PHP je starší formát lokalizačního souboru. Toto je v podstatě pole PHP se všemi zprávami. V jádru MediaWiki je každý jazyk umístěn ve svém vlastním souboru v adresáři languages/message zdrojového kódu MediaWiki. V rozšířeních jsou všechny jazyky a dokumentace zprávy (qqq) ve stejném souboru: ExtensionName.i18n.php, obvykle v hlavním adresáři rozšíření.

K migraci z PHP na JSON použijte skript generateJsonI18n.php. Přesune zprávy do souborů JSON a nahradí text souboru PHP podložkou, která ukazuje na soubory JSON. Tento standardní kód je potřeba pro zpětnou kompatibilitu s MediaWiki 1.19. Nepoužívá se v nových rozšířeních, která nevyžadují kompatibilitu s MediaWiki 1.19.

Používání zpráv
MediaWiki používá centrální úložiště zpráv, na které se odkazují klíče v kódu. To se liší například od, který pouze získává přeložitelné řetězce ze zdrojových souborů. Systém založený na key-based některé věci usnadňuje, jako je upřesňování 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 nemusí synchronizovat. V praxi to není velký problém a jediným významným problémem je, že někdy další zprávy, které se již nepoužívají, stále zůstávají k překladu.

Chcete-li, aby byly klíče zpráv lépe ovladatelné a snadno k nalezení, také pomocí grep, vždy je pište úplně a nespoléhejte se příliš na jejich dynamické vytváření. Můžete zřetězit části klíčů zpráv, pokud máte pocit, že to dává vašemu kódu lepší strukturu, ale přidejte komentář se seznamem možných výsledných klíčů.

Viz také konvence kódu. Například:

Chcete-li použít zprávu v JavaScriptu, musíte ji uvést v definici vašeho modulu ResourceLoader ve vlastnosti.

Podrobné využití funkcí zpráv v PHP a JavaScriptu je na stránce. Toto je důležitá stránka dokumentace a měli byste si ji přečíst, než napíšete kód, který používá zprávy.

Zdroje zpráv
Kód vyhledává systémové zprávy z těchto zdrojů:
 * Jmenný prostor MediaWiki. To umožňuje wiki převzít nebo přepsat všechny své zprávy, když standardní zprávy nevyhovují nebo jsou nežádoucí.
 * MediaWiki:Message-key je výchozí zpráva,
 * MediaWiki:Message-key/language-code je zpráva, která se má použít, pokud uživatel zvolil jiný jazyk, než je výchozí jazyk wiki.
 * Ze souborů zpráv:
 * Samotné jádro MediaWiki a v současnosti udržovaná rozšíření používají soubor pro jazyk s názvem, kde zyx je kód jazyka pro daný jazyk.
 * Některá starší rozšíření používají kombinovaný soubor zpráv obsahující všechny zprávy ve všech jazycích, obvykle pojmenovaný.
 * Mnoho wiki Wikimedia Foundation přistupuje k některým zprávám z rozšíření, což jim umožňuje standardizovat zprávy na wiki WMF, aniž by je vnucovaly každé instalaci MediaWiki.
 * Několik rozšíření používá jiné techniky.

Ukládání do mezipaměti
Systémové zprávy jsou jednou z významnějších součástí MediaWiki, především proto, že se používají v každém webovém požadavku. Soubory zpráv PHP jsou velké, protože obsahují tisíce klíčů a hodnot zpráv. Načtení tohoto souboru (a případně více souborů, pokud se jazyk uživatele liší od jazyka obsahu) činí velké nároky na paměť a výkon. Ke snížení tohoto dopadu na výkon se používá agresivní vrstvený systém ukládání do mezipaměti.

MediaWiki má vestavěno mnoho mechanismů ukládání do mezipaměti, díky kterým je kód poněkud obtížnější pochopit. Od 1.16 je nový systém ukládání do mezipaměti, který ukládá zprávy do mezipaměti buď v souborech cdb nebo v databázi. Přizpůsobené zprávy se ukládají do mezipaměti v souborovém systému a v memcached (nebo alternativně), v závislosti na konfiguraci.

Níže uvedená tabulka poskytuje přehled příslušných nastavení:

V MediaWiki 1.27.0 a 1.27.1 byla autodetekce změněna tak, aby upřednostňovala backend souboru. V případě  (výchozí) se použije backend souboru s cestou z. Pokud tato hodnota není nastavena (což je výchozí hodnota), použije se dočasný adresář určený operačním systémem. Pokud nelze dočasný adresář detekovat, použije se jako záložní řešení backend databáze. Toto bylo vráceno z 1.27.2 a 1.28.0 kvůli konfliktu souborů na sdílených hostitelích a bezpečnostním problémům (viz T127127 a T161453).

Funkce backtrace
Pro lepší vizuální znázornění vrstev ukládání do mezipaměti je zde funkce backtrace toho, jaké metody se nazývají při načítání zprávy. Vysvětlení každé vrstvy najdete v následujících částech.



MessageCache
Třída  je nejvyšší úrovní ukládání zpráv do mezipaměti. Je volána ze třídy Message a vrací konečný nezpracovaný obsah zprávy. Tato vrstva zpracovává následující logiku:


 * Kontrola přepsání zpráv v databázi
 * Ukládání přepsaných zpráv do mezipaměti v nebo v čemkoli, na co je  nastaveno
 * Vyřešení zbytku sekvence jazykové rezervy

Poslední odrážka je důležitá. Jazyková rezerva (language fallbacks) umožňuje MediaWiki použít jiný jazyk, pokud originál neobsahuje požadovanou zprávu. Jak je zmíněno v další části, většina jazykových řešení se vyskytuje na nižší úrovni. Pouze vrstva  však kontroluje, zda v databázi nejsou přepsané zprávy. Zde se tedy provádí integrace přepsaných zpráv z databáze do záložního řetězce. Pokud databázi nepoužíváte, lze celou tuto vrstvu zakázat.

LocalisationCache
Viz LocalisationCache.php

LCStore
Třída  je pouze implementací typu back-end, kterou používá třída LocalisationCache pro skutečné ukládání do mezipaměti a získávání zpráv. Stejně jako třída, která se používá pro obecné ukládání do mezipaměti v MediaWiki, existuje řada různých typů mezipaměti (konfigurovaných pomocí $wgLocalisationCacheConf):
 * "db" (výchozí) - ukládá zprávy do mezipaměti v databázi
 * "file" (výchozí, pokud je nastaveno ) - používá CDB k ukládání zpráv do mezipaměti v místním souboru
 * "accel" - k ukládání dat používá APC nebo jinou mezipaměť operačních kódů

Možnost "file" používá Wikimedia Foundation a je doporučena, protože je rychlejší než přechod do databáze a spolehlivější než mezipaměť APC, zejména proto, že APC není kompatibilní s PHP verze 5.5 nebo novější.

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

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

V názvech zpráv se držte malých písmen, číslic a pomlček; většina ostatních znaků je mezi méně praktickými nebo nefungujícími vůbec. Podle konvence MediaWiki první znak nerozlišuje velká a malá písmena a ostatní znaky rozlišují malá a velká písmena.

Při pojmenovávání prosím dodržujte globální nebo místní konvence. U předpon použijte standardní prefix, nejlépe název předpony psaný malými písmeny, za kterým následuje pomlčka ("-"). Výjimky jsou:


 * Zprávy používané rozhraním API. Musí začínat znaky,  ,  . Za tuto předponu vložte předponu rozšíření. (Všimněte si, že tyto zprávy by měly být v samostatném souboru, obvykle pod includes/i18/api.)
 * Zprávy související s protokolem. Musí začínat znaky,  ,.
 * Uživatelská práva. Klíč pro název práva, jak je zobrazen na Special:ListGroupRights, musí začínat . Název akce, která doplňuje větu "" musí začínat.
 * Značky revizí musí začínat.
 * Speciální názvy stránek musí začínat.

Další věci, které je třeba vzít v úvahu při vytváření zpráv

 * 1) Ujistěte se, že pro zprávu používáte vhodné zpracování (analýzu, nahrazení , escapování pro 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é součásti, jako je Installer, EXIF tagy a ApiHelp, mají své vlastní soubory zpráv.
 * 3) Pokud je vaše zpráva v rozšíření, přidejte ji do souboru   nebo   v příslušném podadresáři. Zejména zprávy API, které vidí pouze vývojáři a ne většina koncových uživatelů, jsou obvykle v samostatném souboru, například  . Pokud má rozšíření 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) Udělejte si pauzu a zvažte znění zprávy. Je to co nejjasnější? Může to být špatně pochopeno? Pokud je to možné, vyžádejte si komentáře od jiných vývojářů nebo lokalizátorů. Postupujte podle Internacionalizační rady.
 * 5) Přidejte dokumentaci do   ve stejném adresáři.

Zprávy, které by se neměly překládat

 * 1) Ignored (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 vyžadovat překlad, protože odkazují pouze na jiné zprávy nebo jazykově neutrální funkce, např. zprávu " ".
 * 2) Optional (volitelné) zprávy mohou být přeloženy pouze v případě, že jsou změněny v cílovém jazyce.

Označení takových zpráv:


 * použijte šablonu v dokumentaci ke zprávě, tj
 * nebo
 * řekněte rozšíření používanému na, co má dělat se zprávami, a to odesláním opravy s uvedením příslušného seznamu (viz také ):
 * pro jádro přidejte klíče zpráv do
 * pod  nebo
 * pod ;
 * pro rozšíření v přidejte pod název rozšíření řádek jako
 * or
 * or

Odebírání existujících zpráv
Odstraňte ji z  a. Neobtěžujte se jinými jazyky. Aktualizace z je zpracují automaticky.

Kromě toho zkontrolujte, zda se zpráva objeví kdekoli v konfiguraci translatewiki, například v seznamu volitelných nebo nejpoužívanějších zpráv (měl by stačit jednoduchý git grep). V případě potřeby jej z těchto seznamů odstraňte.

Změna existujících zpráv

 * 1) Zvažte aktualizaci dokumentace zprávy.
 * 2) Změňte klíč zprávy, pokud staré překlady nejsou vhodné pro nový význam. To zahrnuje také změny ve zpracování zpráv (parsování, escapování, parametry atd.). Zlepšení frázování 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 cílit překladatelé. Změna klíče zprávy nevyžaduje komunikaci s týmem i18n nebo podání žádosti o podporu. Pokud však máte zvláštní okolnosti nebo dotazy, zeptejte se na  nebo na stránce podpory na.
 * 3) Pokud rozšíření podporuje, změňte prosím pouze anglickou zdrojovou zprávu anebo klíč a doprovodný záznam v  . V případě potřeby se tým translatewiki.net postará o aktualizaci překladů, označí je jako zastaralé, vyčistí soubor nebo přejmenuje klíče tam, kde je to možné. To platí také v případě, že měníte pouze věci, jako jsou značky HTML, které byste mohli změnit v jiných jazycích, aniž byste těmito jazyky mluvili. Většina z těchto akcí proběhne v translatewiki.net a dorazí do Gitu s přibližně jednodenním  zpožděním.

Dokumentace zprávy
Pro dokumentaci zpráv existuje pseudojazykový kód. Je to jeden z kódů ISO 639 vyhrazený pro soukromé použití. Tam neuchováváme překlady každé zprávy, ale shromažďujeme anglické věty o každé zprávě: Říká nám, kde se používá, dává rady, jak ji přeložit, a vyjmenovává a popisuje její parametry, odkazuje na související zprávy a tak dále. Na translatewiki.net se tyto rady zobrazují překladatelům, když upravují zprávy.

Programátoři musí zdokumentovat každou zprávu. Dokumentace zpráv je nezbytným zdrojem – nejen pro překladatele, ale pro všechny správce modulu. Kdykoli je do softwaru přidána zpráva, musí být přidána také odpovídající položka. Revize, které tak nečiní, jsou označeny " ", dokud nebude přidána dokumentace.

Dokumentace v souborech  by měla být upravována přímo pouze při přidávání nových zpráv nebo při změně existující anglické zprávy způsobem, který vyžaduje změnu dokumentace, například přidání nebo odebrání parametrů. V ostatních případech by měla být dokumentace obvykle upravována v translatewiki. Každý dokumentační řetězec je přístupný na https://translatewiki.net/wiki/MediaWiki: message-key /qqq, jako by to byl překlad. Tyto úpravy budou exportovány do zdrojových úložišť spolu s překlady.

Mezi užitečné informace, které by měly být v dokumentaci, patří:


 * 1) Práce se zprávami (analýza, escapování, prostý text).
 * 2) Typ parametrů s ukázkovými hodnotami.
 * 3) Kde je zpráva použita (stránky, umístění v uživatelském rozhraní).
 * 4) Jak se zpráva používá tam, kde je použita (název stránky, text tlačítka, atd.).
 * 5) Jaké další zprávy se používají spolu s touto zprávou nebo na které další zprávy se tato zpráva vztahuje.
 * 6) Cokoli jiného, co lze pochopit, když je zpráva viděna v kontextu, ale ne, když je zpráva zobrazena samostatně (což je případ, kdy je překládána).
 * 7) Případně poznámky o gramatice. Například "open" v angličtině může být sloveso i přídavné jméno. V mnoha jiných jazycích se slova liší a je nemožné uhodnout, jak je přeložit bez dokumentace.
 * 8) Přídavná jména, která popisují věci, jako je "disabled" (zakázáno), "open" (otevřeno) nebo "blocked" (blokováno), musí vždy říkat, co popisují. V mnoha jazycích musí mít přídavná jména rod podstatného jména, které popisují. Může se také stát, že různé druhy věcí potřebují různá přídavná jména.
 * 9) Pokud má zpráva speciální vlastnosti, například pokud se jedná o název stránky, nebo pokud by neměla být přímým překladem, ale měla by být přizpůsobena kultuře nebo projektu.
 * 10) Zda se zpráva objeví v souvislosti s jinou zprávou, například v seznamu nebo v nabídce. Znění nebo gramatické rysy slov by pravděpodobně měly být podobné se souvisejícími zprávami. Položky v seznamu by měly také správně souviset se záhlavím seznamu.
 * 11) Části zprávy, které se nesmí překládat, jako jsou názvy obecných jmenných prostorů, adresy URL nebo značky.
 * 12) Vysvětlení potenciálně nejasných slov, například zkratky, jako je "CTA" nebo konkrétní žargon, jako "template" (šablona), "suppress" (potlačit) nebo "stub" (útržek). (Všimněte si, že je nejlepší se takovým slovům v první řadě vyhnout!)
 * 13) Snímky obrazovek (creenshot) jsou velmi užitečné. Neořezávejte – obrázek celé obrazovky, na kterém se zpráva zobrazuje, poskytuje úplný kontext a lze jej znovu použít v několika zprávách.

Několik dalších tipů:


 * 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' documentation.

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:


 * - for  messages
 * - for  messages
 * - for messages around user groups (, ,  ,   and  )
 * - for  messages

Have a look at the template pages for more information.

Internationalisation hints
Besides documentation, translators ask developers 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.

Localisation lists the main places where you can find the assistance of experienced and knowledgeable people regarding i18n.

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-trick, 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 almost never find messages shorter than Chinese ones, rarely shorter than English ones, and 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. Languages may lack the technical vocabulary present in English, and may require multiple words or even complete sentences to explain some concepts. 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 misinterpreted.

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. Also, in Kölsch, they say "corroborator and participant" in one word since any reference to "use" would too strongly imply "abuse". 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 unchanged, 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. 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 unchanged, 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:

…  …, …   …, or
 * 1) via wikitext:
 * 1) via wikitext:
 * 1) 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, and The main reasons why we shouldn't use click here as link text.

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' perspective of 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:

"File renaming failed" -> "There is a file with this name already. Please choose a different name."
 * "The file was successfully renamed" -> "The file was renamed"

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:


 * Spaces and line breaks (new lines) at the end of the message are always automatically removed by the wikitext editor. Your message must not end with a space or line break, as it will be lost when it's edited on the wiki.
 * Spaces and line breaks at the beginning are not automatically removed, but they are likely to be removed by accident during editing, and should be avoided.

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.

There are some messages which require a space at the end, such as 'word-separator' (which consists of just a space character in most languages). To support such use cases, the following HTML entities are allowed in messages and transformed to the actual characters, even if the message otherwise doesn't allow wikitext or HTML formatting:


 * – space
 * or  – non-breaking space
 * – soft hyphen

On a related note, any other syntax elements affected by pre-save transforms also must not be used in messages, as they will be transformed when the message is edited on the wiki.

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

Související odkazy

 * FAQ
 * FAQ
 * FAQ
 * FAQ
 * FAQ
 * FAQ