Localisation

This landing page links to core technical documentation about MediaWiki internationalisation and localisation (i18n and L10n). A core principle of MediaWiki is that i18n must not be an afterthought: it's an essential component even in the earliest phases of software development.

For translators and users

 * Translator hub
 * For translating pages on this wiki, see.
 * How to Translate MediaWiki interface messages
 * Language names reference
 * How to input text in different scripts (IMEs)
 * How to download and enable different webfonts
 * Universal Language Selector FAQ

Help and contact info

 * mediawiki-i18n mailing list
 * translatewiki.net Support page
 * IRC:
 * Find translators for your language
 * File a bug:
 * MediaWiki bug reports for internationalisation
 * Tips for filing a bug
 * Language Engineering team

Messages that should not be translated

 * 1) Ignored messages are those which should exist only in the English messages file.  They are messages that should not need translation, because they reference only other messages or language-neutral features, e.g. a message of "  ".


 * 1) Optional messages may be translated only if changed in the target language.

To flag such messages:


 * (optionally) use the template in the message documentation, that is respectively
 * or
 * (required) tell the extension used on  what to do with the messages by submitting a patch listing them as appropriate (see also ):
 * for core, in add the message keys
 * under or
 * under  ;
 * for extensions, in add a line under the extension's name like
 * or
 * or

Removing existing messages
Remove it from and. Don't bother with other languages. Updates from will handle those automatically.

In addition, check whether the message appears anywhere in translatewiki configuration, for example in the list of optional or most used messages (a simple git grep should be enough). Remove it from these lists if needed.

Changing existing messages

 * 1) Consider updating the message documentation (see #Adding new messages).


 * 1) Change the message key if old translations are not suitable for the new meaning.  This also includes changes in message handling (parsing, escaping, parameters, etc.).  Improving the phrasing of a message without technical changes is usually not a reason for changing a key.  At translatewiki.net, the translations will be marked as outdated so that they can be targeted by translators.  Changing a message key does not require talking to the i18n team or filing a support request.  However, if you have special circumstances or questions, ask in  or in the support page at.


 * 1) If the extension is supported by , please only change the English source message and/or key, and the accompanying entry in  .  If needed, the translatewiki.net team will take care of updating the translations, marking them as outdated, cleaning up the file or renaming keys where possible.  This also applies when you're only changing things like HTML tags which you could change in other languages without speaking those languages.  Most of these actions will take place in translatewiki.net and will reach Git with about one day of delay.

Localising namespaces and special page aliases
and special page names (i.e. " RecentChanges " in " Special:RecentChanges ") are also translatable.

Namespaces


Currently making namespace name translations is disabled on translatewiki.net, so you need to do this yourself in Gerrit, or file a  task asking for someone else to do it.

To allow custom namespaces introduced by your extension to be translated, create a file that looks like this:

Then load it from the file using ExtensionMessagesFiles like this:

Now, when a user installs MyExtension on their Finnish (fi) wiki, the custom namespace will be translated into Finnish magically, and the user doesn't need to do a thing!

Also remember to register your extension's namespace(s) on the page.

Special page aliases
See for up-to-date information. The following does not appear to be valid.

Create a new file for the special page aliases in this format:

Then load it from the file using ExtensionMessagesFiles like this:

When your special page code uses either or  (in the class that provides Special:MyExtension ), the localised alias will be used, if it's available.

Update of localisation
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.

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:


 * Checking for message overrides in the database


 * Caching over-ridden messages in, or whatever  is set to


 * Resolving the remainder of the sequence

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.

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


 * "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

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.

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.


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

What can be localised
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)




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


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

See #Message sources.