Formato de arquivo de localização

This page is a translated version of the page Localisation file format and the translation is 100% complete.
Other languages:
English • ‎Türkçe • ‎português do Brasil

Todas as mensagens no MediaWiki são definidas em um arquivo de mensagens.

Existem dois tipos de arquivos de mensagens no MediaWiki: JSON e PHP. Já que em abril de 2014, o core da MediaWiki e a maioria das extensões mantidas foram migradas para o formato JSON. Para mais informações sobre a migração para JSON, veja Requests for comment/Localisation format. Ambos os formatos são suportados, mas você deve usar JSON para todos os seus novos desenvolvimentos. Suporte ao PHP será removido no futuro; isso será anunciado separadamente.

JSON

Starting from late 2013 a new file format for messages was introduced: JSON. This is plain JSON, familiar as a common generic data storage format. Every key in it is a message key, and the value is the message text. In addition, the special @metadata key is used to store information about the translation, such as the translation authors.

Using JSON makes the localisation files more secure because it's not executable. It is also compatible with jquery.i18n, a JavaScript library developed as part of Project Milkshake, which provides MediaWiki-like frontend localisation capabilities and is used by some extensions that want to be less dependent on MediaWiki, such as VisualEditor and UniversalLanguageSelector.

Because the wider suite of internationalisation and localisation tools were called "Project Milkshake", some people call this format "banana".

File location

In MediaWiki core, localisation files are placed in the languages/i18n directory. MediaWiki extensions usually place theirs in an i18n/ subdirectory. If a large number of messages exist within a project, one may want to split these into two or more topical subdirectories for maintainability. In MediaWiki context, the $wgMessagesDirs configuration key is used to list these subdirectories. Here's an example from the VisualEditor extension for MediaWiki:

{
  "MessagesDirs": {
    "VisualEditor": [
      "lib/ve/modules/ve/i18n",
      "modules/ve-mw/i18n",
      "modules/ve-wmf/i18n",
      "lib/ve/lib/oojs-ui/i18n"
    ]
  }
}

You add new messages to the English "en" messages file en.json and document them in the message documentation file with the special pseudo-language code "qqq" – qqq.json. See also: Localisation#Adding new messages.

Metadata

Currently the following metadata fields are used in the files:

authors
A JSON list of the authors of the messages. For English (en) and message documentation (qqq) these are added manually when the messages file is edited. For all other languages this is inserted automatically when the message file is exported from translatewiki.net. Message documentation can be edited on translatewiki.net, and documentation editors are inserted to the qqq.json automatically as well.
message-documentation
This is the pseudo-language code for storing the message documentation. For MediaWiki this is always qqq. (This appears in some extensions, but it's not actually processed in any way. It's not mandatory.)

Conventions

Special characters like line breaks are escaped ("\n").

Unicode characters that represent letters in different alphabets are stored as real characters and not as character codes, because these files are sometimes read by people and because this makes the files smaller ("誼" and not "\u8ABC"). In any case, developers have few reasons to edit messages in any languages except English, because these are usually edited through translatewiki.net.

HTML code is not escaped either, so "<strong>Warning</strong>" and not "\u003cstrong\u003eWarning\u003c/strong\u003e".

The JSON files are indented using tabs.

PHP

The older localisation file format is PHP. This is essentially a PHP array with all the messages. In core MediaWiki each language resides in its own file in the languages/message directory of the MediaWiki source code. In the extensions all the languages and the message documentation (qqq) are in the same file: ExtensionName.i18n.php, usually in the main directory of the extension.

To migrate from PHP to JSON use the generateJsonI18n.php script. It will move the messages to JSON files and replace the text of the PHP file with a shim that points to the JSON files. This boilerplate code is needed for backwards compatibility with MediaWiki 1.19. It is not used in new extensions that do not require MediaWiki 1.19 compatibility.