View source for Help:System message/ps

<languages />
{{PD Help Page}}
{{i18n navigation}}
[[File:MediaWiki SpecialUpload interface labelled.png|thumb|<span lang="en" dir="ltr" class="mw-content-ltr">Labelled diagram of the [[Special:Upload]] form, showing various system messages.</span>]]
<span lang="en" dir="ltr" class="mw-content-ltr">A '''system message''' is a snippet of plain text (nowiki), wikitext, [[w:CSS|CSS]], or [[w:JavaScript|JavaScript]] that can be used to customize the behavior of MediaWiki and its appearance for each language and [[w:Locale (computer software)|locale]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki uses messages for any user-facing part of the interface, allowing for internationalization and localization of the MediaWiki UI, for both core and extensions.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">All messages used in MediaWiki are defined in a [[#Localisation file format|messages file]].</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Overriding messages on-wiki ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Messages can be overridden from their default values by editing them on-wiki.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Each message has a wiki page in the MediaWiki namespace with its message key as the name of the page.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example, the "aboutsite" message is stored at MediaWiki:aboutsite.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">By default this namespace is restricted from editing unless the user has the "editinterface" permission.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">A list of all message pages can be found on [[Special:AllMessages]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Editing interface messages is typically straightforward, just like editing a normal wiki page, but it is restricted to users with the [[Special:MyLanguage/editinterface|editinterface]] permission, which is assigned to administrators (and interface administrators) by default.</span>
[[File:Wiki-system-messages.png|thumb|<span lang="en" dir="ltr" class="mw-content-ltr">Example row on the old [[Special:AllMessages]].</span>]]
<span lang="en" dir="ltr" class="mw-content-ltr">The [[Special:AllMessages]] table contains two columns: the linked interface name, and the text.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The text is horizontally split to show the default text above, and the customized text below.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">When a custom message does not exist, only the default will be shown.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To customize a message, click the upper link in the left column (the name of the message).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This link is red if the default text is in use, because the edit page is empty.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The lower links in the left column cells lead to the discussion pages for that message.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Overriding messages on the wiki is recommended only in the following cases:
</div>

* <span lang="en" dir="ltr" class="mw-content-ltr">The message has a severe mistake that must be fixed as soon as possible.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In this case, it's recommended to also fix this mistake in the source code if it's in English or in the translation on translatewiki if it's not.</span> <span lang="en" dir="ltr" class="mw-content-ltr">When the correction is deployed, the page with the local customization should be deleted.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">If the local wiki uses different terminology.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example, many messages use the word "page", but the English Wikipedia often says "article" instead.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The local message is trying to add some unique functionality, for example for a gadget or a template.</span> <span lang="en" dir="ltr" class="mw-content-ltr">(In such a case, it is still recommended to consider changing the source message or to encapsulate this functionality in an extension, so that other wikis would be able to enjoy it conveniently, without having to copy customizations manually.)</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
== Finding messages and documentation ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">How each message is used by MediaWiki, variables available, parameters used, limitations, et cetera is explained with the [//translatewiki.net/w/i.php?title=Special:Translate&task=reviewall&group=core&language=qqq&limit=5000&action=page&filter= complete documentation in the qqq pseudo-language] files, as per [[#Message_documentation|message documentation guidelines]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Some longer explanation pages may exist for some interface messages at the older {{ll|Category:Interface messages}}.</span>

{{note
|1=<span lang="en" dir="ltr" class="mw-content-ltr">In the wiki base of translatewiki.net, qqq is the page which holds the user documentation of the message (in English because it is the same shown to all readers).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In the same way as /en, /zu, /fr, ..., /qqq is a subpage of the article and is viewable directly.</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">Try [[translatewiki:MediaWiki:Tog-hideminor/en]] to view a message in English,</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Try [[translatewiki:MediaWiki:Tog-hideminor/fr]] to view the same message in French,</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Try [[translatewiki:MediaWiki:Tog-hideminor/qqq]] to display its associated documentation (in English).</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
From this point of view <code>qqq</code> is considered as a language in parameter <code>language=</code> of the request.
</div>
}}

{{MW 1.18|and later}}
<span lang="en" dir="ltr" class="mw-content-ltr">In MediaWiki 1.18 and above, you can find a message key by browsing a wiki in the special pseudo-language code <code>'''[[Special:MyLanguage/Help:Qqx|qqx]]'''</code>, which can be done by appending <code>?[[Special:MyLanguage/uselang|uselang]]=qqx</code> to the URL, or <code>&uselang=qqx</code> if the URL already contains a <code>?</code> character ([{{fullurl:{{FULLPAGENAME}}|uselang=qqx}} example]).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">All the messages will then be replaced by their message keys, so you can identify which message is responsible.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Messages that are always in the content language will not be shown using qqx.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
In case the page uses tabs like e.g. [[Special:Preferences#mw-prefsection-rendering|special page "Preferences"]] you will have to add the tab after the <code>uselang</code> parameter, e.g. <code>Special:Preferences?uselang=qqx#mw-prefsection-rendering</code>.
</div>

{{MW 1.38|and later|gerrit change=765385}}
<span lang="en" dir="ltr" class="mw-content-ltr">Before MediaWiki 1.38, fallback message keys were not shown, which made it difficult to identify the source of some messages, notably the [[Special:MyLanguage/Help:Navigation#Page tabs|page navigation tabs]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Since MediaWiki 1.38 fallback message keys are shown separated by slashes (<code>/</code>).</span>

{{MW 1.43|and later|gerrit change=1025837}}
<span lang="en" dir="ltr" class="mw-content-ltr">Before MediaWiki 1.43, override message keys (using hooks like {{ll|Manual:Hooks/MessageCacheFetchOverrides|MessageCacheFetchOverrides}}) were not shown either, which made it difficult to identify the source of messages overridden by extensions (such as {{ll|Extension:WikimediaMessages|WikimediaMessages}}).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Since MediaWiki 1.43 override message key is shown after an equals sign (<code>=</code>).</span>

{{Anchor|Messages file}}
<div lang="en" dir="ltr" class="mw-content-ltr">
== Localisation file format ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
All messages used in MediaWiki are defined in a ''messages file''.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">There are two types of message files in MediaWiki: JSON and PHP.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">As of April 2014, core MediaWiki and most of the maintained extensions were migrated to the JSON format.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You should use JSON for all new development.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For more information about the migration to JSON see [[Requests for comment/Localisation format]].</span>

=== JSON ===

<span lang="en" dir="ltr" class="mw-content-ltr">Starting from late 2013 a new file format for messages was introduced: JSON.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is plain [[:w:JSON|JSON]], familiar as a common generic data storage format.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Every key in it is a message key, and the value is the message text.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In addition, the special <code>@metadata</code> key is used to store information about the translation, such as the translation authors.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Using JSON makes the localisation files more secure because it's not executable.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is also compatible with jquery.i18n, a JavaScript library developed as part of [[Milkshake|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 [[Special:MyLanguage/Extension:VisualEditor|VisualEditor]] and [[Special:MyLanguage/Extension:UniversalLanguageSelector|UniversalLanguageSelector]].</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Because the wider suite of internationalisation and localisation tools were called "[[Project Milkshake]]", some people call this format "banana".
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== File location ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">In MediaWiki core, localisation files are placed in the <code>{{git file |file=languages/i18n |action=tree}}</code> directory.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki extensions usually place theirs in an <code>i18n/</code> subdirectory.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If a large number of messages exist within a project, one may want to split these into two or more topical subdirectories for maintainability.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In MediaWiki context, the {{ll|Manual:$wgMessagesDirs|$wgMessagesDirs}} configuration key is used to list these subdirectories.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Here's an example from the VisualEditor extension for MediaWiki:</span>

<syntaxhighlight lang="json">
{
  "MessagesDirs": {
    "VisualEditor": [
      "lib/ve/modules/ve/i18n",
      "modules/ve-mw/i18n",
      "modules/ve-wmf/i18n",
      "lib/ve/lib/oojs-ui/i18n"
    ]
  }
}
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">You add new messages to the English <code>en</code> messages file <code>en.json</code> and document them in the message documentation file with the special pseudo-language code <code>qqq</code> &ndash; <code>qqq.json</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">''See also: [[#Adding new messages|Adding new messages]]''.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Metadata ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Currently the following metadata fields are used in the files:
</div>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Conventions ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Special characters like line breaks are escaped (<code>"\n"</code>).
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">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 (<code>"誼"</code> and not <code>"\u8ABC"</code>).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In any case, developers have few reasons to edit messages in any languages except English, because these are usually edited through translatewiki.net.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
HTML code is not escaped either, so <code>"&lt;strong>Warning&lt;/strong>"</code> and not <code>"\u003cstrong\u003eWarning\u003c/strong\u003e"</code>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The JSON files are indented using tabs.
</div>

=== PHP ===

{{note|type=warn|1=<span lang="en" dir="ltr" class="mw-content-ltr">This section refers to the use of [[MessagesXx.php]] files for localizing messages, which has been [[Requests for comment/Localisation format|deprecated in 2014]].</span> <span lang="en" dir="ltr" class="mw-content-ltr">However, the files are still used for {{ll|Manual:Language#What can be localised|other language-specific configuration}}.</span>}}

<span lang="en" dir="ltr" class="mw-content-ltr">The older localisation file format is PHP.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is essentially a PHP array with all the messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In core MediaWiki each language resides in its own file in the languages/message directory of the MediaWiki source code.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">To migrate system messages from PHP to JSON, use the {{ll|Manual:GenerateJsonI18n.php|generateJsonI18n.php}} script.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This boilerplate code is needed for backwards compatibility with MediaWiki 1.19.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is not used in new extensions that do not require MediaWiki 1.19 compatibility.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Using messages ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki uses a ''central'' repository of messages which are referenced by keys in the code.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is different from, for example, the [https://www.gnu.org/software/gettext/ gettext] system, which extracts the translatable strings from the source files.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The key-based system makes some things easier, like refining the original texts and tracking changes to messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The drawback is that the list of used messages and the list of source texts for those keys can get out of sync.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In practice this isn't a big problem, and the only significant problem is that sometimes extra messages that are not used anymore still stay up for translation.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Making messages findable ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">To make message keys more manageable and easier to search for, always write them completely and don't rely too much on creating them dynamically.</span>
{{tmpl
|0=<span lang="en" dir="ltr" class="mw-content-ltr">You may concatenate parts of message keys if you feel that it gives your code better structure — but only do this when there definitely are multiple possibilities,$1 and be sure to put a comment nearby with a list of the possible resulting keys.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example:</span>
|1=<ref><span lang="en" dir="ltr" class="mw-content-ltr">Some linters will reject message lists with just one item, e.g.: [https://github.com/wikimedia/eslint-plugin-mediawiki/issues/57 mediawiki/msg-doc doesn't accept valid docs with 1 entry].</span></ref>
}}

<syntaxhighlight lang="php">
// Messages that can be used here:
// * myextension-connection-success
// * myextension-connection-warning
// * myextension-connection-error
$text = wfMessage( 'myextension-connection-' . $status )->parse();
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
See also the [[Special:MyLanguage/Manual:Coding_conventions#Dynamic_identifiers|coding conventions for dynamic identifiers]].
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Loading messages for use in JavaScript code ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
To use a message in JavaScript, you have to [[Special:MyLanguage/Manual:Messages API#Using a ResourceLoader module|list it]] in the definition of your ResourceLoader module, in the <code>"messages"</code> property.
</div>

=== Message usage functions ===

<span lang="en" dir="ltr" class="mw-content-ltr">The detailed use of message functions in PHP and JavaScript is on {{ll|Manual:Messages API}}.</span>
'''<span lang="en" dir="ltr" class="mw-content-ltr">This is an important documentation page, and you should read it before you write code that uses messages.</span>'''
<div lang="en" dir="ltr" class="mw-content-ltr">
== Message sources ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Code looks up system messages from these sources:
</div>
* <span lang="en" dir="ltr" class="mw-content-ltr">The MediaWiki namespace.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This allows wikis to adopt, or override, all of their messages, when standard messages do not fit or are not desired.</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki:''Message-key'' is the default message,</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">From message files:</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">Core MediaWiki itself and most currently maintained [[Special:MyLanguage/Category:All extensions|extensions]] use a file per language, named <code>''zyx''.json</code>, where ''zyx'' is the language code for the language.</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">Some older extensions use a combined message file holding all messages in all languages, usually named {{tmpl|0=<code>''$1''.i18n.php</code>|MyExtensionName}}.</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">Many Wikimedia Foundation wikis access some messages from the {{ll|Extension:WikimediaMessages|nsp=0}} extension, allowing them to standardise messages across WMF wikis without imposing them on every MediaWiki installation.</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">A few extensions use other techniques.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Caching ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">System messages are one of the more significant components of MediaWiki, primarily because it is used in every web request.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The PHP message files are large, since they store thousands of message keys and values.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">An aggressive, layered caching system is used to reduce this performance impact.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki has lots of caching mechanisms built in, which make the code somewhat more difficult to understand.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Since 1.16 there is a new caching system, which caches messages either in [[cdb]] files or in the database.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Customised messages are cached in the filesystem and in [[Special:MyLanguage/memcached|memcached]] (or alternative), depending on the configuration.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">The table below gives an overview of the settings involved:</span>

{|class="wikitable"
|-
!colspan="2" rowspan="2"| <span lang="en" dir="ltr" class="mw-content-ltr">Location of cache storage</span>
!colspan="4"| {{ll|Manual:$wgLocalisationCacheConf|$wgLocalisationCacheConf}}
|-
! 'store' => 'db'<br />&nbsp; !! 'store' => 'detect'<br />(<span lang="en" dir="ltr" class="mw-content-ltr">default</span>) !! 'store' => 'files'<br />&nbsp; !! 'store' => 'array'<br />''(<span lang="en" dir="ltr" class="mw-content-ltr">experimental since MW ≥ 1.26</span>)''
|-
!rowspan="2"| {{ll|Manual:$wgCacheDirectory|$wgCacheDirectory}}
! = false<br />(<span lang="en" dir="ltr" class="mw-content-ltr">default</span>)
| {{ll|Manual:l10n_cache table|l10n_cache}}
| {{ll|Manual:l10n_cache table|l10n_cache}}
| ''<span lang="en" dir="ltr" class="mw-content-ltr">error</span>'' (<span lang="en" dir="ltr" class="mw-content-ltr">undefined path</span>) || ''<span lang="en" dir="ltr" class="mw-content-ltr">error</span>'' (<span lang="en" dir="ltr" class="mw-content-ltr">undefined path</span>)
|-
! = ''path''
| {{ll|Manual:l10n_cache table|l10n_cache}}
| <span lang="en" dir="ltr" class="mw-content-ltr">local filesystem</span> (CDB) || <span lang="en" dir="ltr" class="mw-content-ltr">local filesystem</span> (CDB) || <span lang="en" dir="ltr" class="mw-content-ltr">local filesystem (PHP array)</span>
|}
{{MW version|version=1.27.0|version2=1.27.2|gerrit change=Id3e2d2b18ddb423647bf2e893bcf942722c0e097}}
<span lang="en" dir="ltr" class="mw-content-ltr">In MediaWiki 1.27.0 and 1.27.1, the autodetection was changed to favor the file backend.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In case <code>'store' => 'detect'</code> (the default), the file backend is used with the path from {{ll|Manual:$wgCacheDirectory|$wgCacheDirectory}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If this value is not set (which is the default), a temporary directory determined by the operating system is used.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If a temporary directory cannot be detected, the database backend is used as a fallback.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This was reverted from 1.27.2 and 1.28.0 because of conflict of files on shared hosts and security issues (see [[:phab:T127127|T127127]] and [[:phab:T161453|T161453]]).</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Function backtrace ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">To better visually depict the layers of caching, here is a function backtrace of what methods are called when retrieving a message.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">See the below sections for an explanation of each layer.</span>

* <code>Message::fetchMessage()</code>
* <code>MessageCache::get()</code>
* <code>Language::getMessage()</code>
* <code>LocalisationCache::getSubitem()</code>
* <code>LCStore::get()</code>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== MessageCache ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The <code>MessageCache</code> class is the top level of caching for messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is called from the Message class and returns the final raw contents of a message.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This layer handles the following logic:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">Checking for message overrides in the database</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Caching over-ridden messages in {{ll|memcached}}, or whatever {{ll|Manual:$wgMessageCacheType|$wgMessageCacheType}} is set to</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Resolving the remainder of the [[Special:MyLanguage/Manual:Language#Fallback languages|language fallback]] sequence</span>

<span lang="en" dir="ltr" class="mw-content-ltr">The last bullet is important.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">[[Special:MyLanguage/Manual:Language#Fallback languages|Language fallbacks]] allow MediaWiki to fall back on another language if the original does not have a message being asked for.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">As mentioned in the next section, most of the language fallback resolution occurs at a lower level.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">However, only the <code>MessageCache</code> layer checks the database for overridden messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Thus integrating overridden messages from the database into the fallback chain is done here.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If not using the database, this entire layer can be disabled.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== LocalisationCache ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
See {{ll|Manual:LocalisationCache.php|LocalisationCache.php}}
</div>

=== LCStore ===

<span lang="en" dir="ltr" class="mw-content-ltr">The <code>LCStore</code> class is merely a back-end implementation used by the LocalisationCache class for actually caching and retrieving messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Like the <code>BagOStuff</code> class, which is used for general caching in MediaWiki, there are a number of different cache types (configured using {{ll|Manual:$wgLocalisationCacheConf|$wgLocalisationCacheConf}}):</span>

* <code>db</code> <span lang="en" dir="ltr" class="mw-content-ltr">(default) – Caches messages in the database</span>
* <code>file</code> <span lang="en" dir="ltr" class="mw-content-ltr">(default if <code>$wgCacheDirectory</code> is set) – Uses [[w:cdb (software)|CDB]] to cache messages in a local file</span>
* <code>accel</code> – <span lang="en" dir="ltr" class="mw-content-ltr">Uses [[Special:MyLanguage/Manual:Caching|APC]] or another opcode cache to store the data</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The <code>file</code> 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.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Adding new messages ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Choosing the message key ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">See also:</span>
{{ll|Manual:Coding conventions#System messages}}

<span lang="en" dir="ltr" class="mw-content-ltr">The message key must be globally unique.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This includes core MediaWiki and all the extensions and skins.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Stick to lower case letters, numbers, and dashes in message names; most other characters are between less practical or not working at all.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Per MediaWiki convention, first character is case-insensitive and other chars are case-sensitive.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Please follow global or local conventions for naming.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For extensions, use a standard prefix, preferably the extension name in lower case, followed by a hyphen (<code>-</code>).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Exceptions are:</span>

; <span lang="en" dir="ltr" class="mw-content-ltr">Messages used by the Action API</span>
: <span lang="en" dir="ltr" class="mw-content-ltr">These must begin with <code>apihelp-</code>, <code>apiwarn-</code>, <code>apierror-</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">After this prefix put the extension prefix.</span> (<span lang="en" dir="ltr" class="mw-content-ltr">Note that these messages should be in a separate file, usually under [[phab:source/mediawiki/browse/master/includes/api/i18n/|includes/i18/api]].</span>)
; <span lang="en" dir="ltr" class="mw-content-ltr">Messages used by the REST API</span>
: <code>rest-module-</code>, <code>rest-endpoint-desc-<HTTP_METHOD></code>, <code>rest-endpoint-summ-<HTTP_METHOD></code>, <code>rest-param-desc</code>, <code>rest-property-desc</code>, <code>rest-schema-desc</code>. <span lang="en" dir="ltr" class="mw-content-ltr">After this prefix put the extension prefix.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Note that these messages should be in a separate file, usually under [[phab:source/mediawiki/browse/master/includes/Rest/i18n/|includes/i18/Rest]].</span>
; <span lang="en" dir="ltr" class="mw-content-ltr">Log-related messages</span>
: <span lang="en" dir="ltr" class="mw-content-ltr">These must begin with <code>logentry-</code>, <code>log-name-</code>, <code>log-description</code>.</span>
; <span lang="en" dir="ltr" class="mw-content-ltr">User rights</span>
: <span lang="en" dir="ltr" class="mw-content-ltr">The key for the name of the right as displayed on Special:ListGroupRights must begin with <code>right-</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The name of the action that completes the sentence <code>{{int|Permissionserrorstext-withaction|unused}}</code> must begin with <code>action-</code>.</span>
; <span lang="en" dir="ltr" class="mw-content-ltr">Revisions tags</span>
: <span lang="en" dir="ltr" class="mw-content-ltr">Revisions tags must begin with <code>tag-</code>.</span>
; <span lang="en" dir="ltr" class="mw-content-ltr">Special page titles</span>
: <span lang="en" dir="ltr" class="mw-content-ltr">Special page titles must begin with <code>special-</code>.</span>
; <span lang="en" dir="ltr" class="mw-content-ltr">Extension descriptions</span>
: <span lang="en" dir="ltr" class="mw-content-ltr">Extension descriptions must begin with the extension name and end with <code>-desc</code>.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
They appear in the table on [[Special:Version]], and their content must briefly explain what the extension does.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Gender ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">English messages almost never need different words that change because of a user's gender.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">English only needs this in the third-person pronouns ("he" and "she"), but these are surprisingly rare in messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">When this is necessary, use <code><nowiki>{{GENDER:$1|he|she|they}}</nowiki></code>.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">However, many other languages need different words depending on the user's gender, not only for third-person pronouns, but also for other pronouns, as well as for verbs in different tenses (e.g. "created", "deleted"), nouns (e.g. "mentor", "administrator"), adjectives (e.g. "new"), etc.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">It is therefore often useful to use <code>GENDER</code> in English messages, even when there's only one English word.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">This gives translators a hint that <code>GENDER</code> can be used in a message.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">It also avoids warnings on translatewiki about missing parameters when an optional username parameter is missing (this happens especially often in log entry messages).</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Other things to note when creating messages ===
</div>
# <span lang="en" dir="ltr" class="mw-content-ltr">Make sure that you are using suitable handling for the message (parsing, <code><nowiki>{{</nowiki></code>-replacement, escaping for HTML, etc.)</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">If your message is part of core, it should usually be added to <code>languages/i18n/en.json</code>, although some specific components, such as Installer, EXIF tags, ApiHelp, preferences, and some others, have their own message files.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">If your message is in an extension add it to the <code>i18n/en.json</code> file or the <code>en.json</code> file in the appropriate subdirectory.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In particular, API messages that are only seen by developers and not by most end users are usually in a separate file, such as <code>i18n/api/en.json</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If an extension has a lot of messages, you may create subdirectories under <code>i18n</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">All the message directories, including the default <code>i18n/</code>, must be listed in the <code>MessagesDirs</code> section in <code>extension.json</code> or in the {{ll|Manual:$wgMessagesDirs|$wgMessagesDirs}} variable.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Take a pause and consider the wording of the message.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Is it as clear as possible?</span> <span lang="en" dir="ltr" class="mw-content-ltr">Can it be misunderstood? Ask for comments from other developers or localisers if possible.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Follow the [[#Internationalisation hints|Internationalisation hints]].</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Add documentation to <code>qqq.json</code> in the same directory.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Don't sort messages arbitrarily by the alphabet.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The sequence of the messages in the file should roughly conform to the features of your project.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Put messages from the same feature next to each other.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This helps translators stay focused and be efficient and consistent.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">If a message or its documentation (<code>qqq</code>) refers to another message in the same JSON file, try to put this message after the message to which it refers, so that translators will have a chance to translate the referred message before they translate the referring message.</span> <span lang="en" dir="ltr" class="mw-content-ltr">It's not always possible, for example when messages refer to each other, but please try to do it whenever it is possible.</span> (<span lang="en" dir="ltr" class="mw-content-ltr">The referring is usually done using the {{tmpl|0=<code><nowiki>{{int:</nowiki>$1<nowiki>}}</nowiki></code>|''key''}} magic word in the message itself or using the <code><nowiki>{{msg-mw}}</nowiki></code> template in the <code>qqq</code> documentation.</span> <span lang="en" dir="ltr" class="mw-content-ltr">See the section on [[#Message_documentation|Message documentation]].</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Put the messages that are expected to be the most basic and the most frequently used in the beginning of the file, and the messages that are rarer and more technically advanced towards the end.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Messages that should not be translated ==
</div>
# <span lang="en" dir="ltr" class="mw-content-ltr">'''Ignored''' messages are those which should exist only in the English [[#Localisation file format|messages file]].</span> <span lang="en" dir="ltr" class="mw-content-ltr">They are messages that should not need translation, because they reference only other messages or language-neutral features, ''e.g.'' a message of <code><nowiki>{{SITENAME}}</nowiki></code>.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">'''Optional''' messages may be translated only if changed in the target language.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
To flag such messages:
</div>

* <span lang="en" dir="ltr" class="mw-content-ltr">use the template in the <code>qqq</code> message documentation, that is respectively</span>
*# <code>{<nowiki/>{[[translatewiki:Template:Notranslate|notranslate]]}}</code> <span lang="en" dir="ltr" class="mw-content-ltr">or</span>
*# <code>{<nowiki/>{[[translatewiki:Template:Optional|optional]]}}</code>;
* <span lang="en" dir="ltr" class="mw-content-ltr">Configure where the messages are exposed for translation:</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">For ignored messages in core, add the message keys to {{git file|project=mediawiki/core|file=languages/i18n/nontranslatable/en.json}} and their documentation to {{git file|project=mediawiki/core|file=languages/i18n/nontranslatable/qqq.json}}.</span> <span lang="en" dir="ltr" class="mw-content-ltr">These files are used instead of listing the messages in translatewiki group configuration.</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">for optional messages in core, submit a patch to {{git file|project=translatewiki|file=groups/MediaWiki/MediaWiki.yaml}} and add the message keys under <code dir="ltr">optional:</code></span>;
** <span lang="en" dir="ltr" class="mw-content-ltr">for extensions, submit a patch to {{git file|project=translatewiki|file=groups/MediaWiki/mediawiki-extensions.txt}} and add a line under the extension's name like</span>
**# <code>ignored = ''msg-key-1'',''msg-key-2''</code> or
**# <code>optional = ''msg-key-1'',''msg-key-2''</code>.

<div lang="en" dir="ltr" class="mw-content-ltr">
== Removing existing messages ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Remove it from <code>en.json</code> and <code>qqq.json</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Don't bother with other languages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Updates from {{ll|translatewiki.net|translatewiki.net}} will handle those automatically.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">In addition, check whether the message appears anywhere in translatewiki configuration, for example in the list of optional, ignored, or most used messages (a simple git grep should be enough).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Remove it from these lists if needed.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Changing existing messages ==
</div>
# <span lang="en" dir="ltr" class="mw-content-ltr">Consider updating the [[#Message documentation | message documentation]].</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Change the message key if old translations are not suitable for the new meaning.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This also includes changes in message handling (parsing, escaping, parameters, etc.).</span> <span lang="en" dir="ltr" class="mw-content-ltr">Improving the phrasing of a message without technical changes is usually not a reason for changing a key.</span> <span lang="en" dir="ltr" class="mw-content-ltr">At translatewiki.net, the translations will be marked as outdated so that they can be targeted by translators.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Changing a message key does not require talking to the i18n team or filing a support request.</span> <span lang="en" dir="ltr" class="mw-content-ltr">However, if you have special circumstances or questions, ask in {{irc|translatewiki}} or in the [[translatewiki:Support|support page]] at {{ll|translatewiki.net|translatewiki.net}}.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">If the extension is supported by {{ll|translatewiki.net|translatewiki.net}}, please only change the English source message and/or key, and the accompanying entry in <code>qqq.json</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">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.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This also applies when you're only changing things like HTML tags which you could change in other languages without speaking those languages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Most of these actions will take place in [[translatewiki:|translatewiki.net]] and will reach Git with about one day of delay.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Message documentation ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">There is a pseudo-language code <code>qqq</code> for message documentation.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is one of the ISO 639 codes reserved for private use.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">There, we do not keep translations of each message, but collect English sentences ''about each message'': telling us where it is used, giving hints about how to translate it, and enumerating and describing its parameters, link to related messages, and so on.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In [[translatewiki:|translatewiki.net]], these hints are shown to translators when they edit messages.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Programmers must document each and every message.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Message documentation is an essential resource – not just for translators, but for all the maintainers of the module.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Whenever a message is added to the software, a corresponding <code>qqq</code> entry ''must'' be added as well; revisions which don't do so are marked <code>V-1</code> until the documentation is added.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Documentation in <code>qqq</code> 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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In other cases, documentation should usually be edited in translatewiki.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Each documentation string is accessible at <nowiki>https://translatewiki.net/wiki/MediaWiki:</nowiki>''message-key''<nowiki>/qqq</nowiki>, as if it were a translation.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">These edits will be exported to the source repositories along with the translations.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Useful information that should be in the documentation includes:</span>

# <span lang="en" dir="ltr" class="mw-content-ltr">Message handling (parsing, escaping, plain text).</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Type of parameters with example values.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Where the message is used (pages, locations in the user interface).</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">How the message is used where it is used (a page title, button text, ''etc.'').</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">What other messages are used together with this message, or which other messages this message refers to.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">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).</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">If applicable, notes about grammar.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example, "open" in English can be both a verb and an adjective.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In many other languages the words are different and it's impossible to guess how to translate them without documentation.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Adjectives that describe things, such as "disabled", "open" or "blocked", must ''always'' say what are they describing.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In many languages adjectives must have the gender of the noun that they describe.</span> <span lang="en" dir="ltr" class="mw-content-ltr">It may also happen that different kinds of things need different adjectives.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Whether the message appears near other message, for example in a list or a menu.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The wording or the grammatical features of the words should probably be similar to the messages nearby.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Also, items in a list may have to be properly related to the heading of the list.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Parts of the message that must not be translated, such as generic namespace names, URLs or tags.</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Explanations of potentially unclear words, for example abbreviations, like "CTA", or specific jargon, like "template", "suppress" or "stub".</span> <span lang="en" dir="ltr" class="mw-content-ltr">(Note that it's best to avoid such words in the first place!)</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">Screenshots are very helpful.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Don't crop – an image of the full screen in which the message appears gives complete context and can be reused in several messages.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
A few other hints:
</div>

* <span lang="en" dir="ltr" class="mw-content-ltr">Remember that very, very often translators translate the messages without actually using the software.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Most usually, translators do not have any context information, neither of your module, nor of other messages in it.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">A rephrased message alone is useless in most circumstances.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Don't use designers' jargon like "hamburger", "nav", or "comps".</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Consider writing a [[betawiki:Terminology#Terminologies|glossary]] of the technical terms that are used in your module.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If you do it, link to it from the messages' documentation.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Message documentation is shown on translatewiki and parsed as wikitext.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If you use mention wikitext or HTML tags that are supposed to be shown as is and not parsed, use {{tag|nowiki|open}}.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">You can link to other messages by using {{tmpl|0=<code>{{((}}msg-mw{{!}}message key{{))}}</code>|message key}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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 the same context.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
translatewiki.net provides some default templates that should be used in documentation, for example:
</div>

;<code><nowiki>{{</nowiki>[[translatewiki:Template:Doc-action|doc-action]]|[...]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">for <code>action-</code> messages</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Template:Doc-right|doc-right]]|[...]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">for <code>right-</code> messages</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Template:Doc-group|doc-group]]|[...]|[...]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">for messages around user groups (<code>group</code>, <code>member</code>, <code>page</code>, <code>js</code> and <code>css</code>)</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Template:Doc-accesskey|doc-accesskey]]|[...]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">for <code>accesskey-</code> messages</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Category:MediaWiki API Message Documentation Templates|doc-api*]]|[...]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">a set of templates for API help and API error messages</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Category:MediaWiki API Message Documentation Templates|doc-api*]]|[...]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">a set of templates for API help and API error messages</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Template:Experimental|experimental]]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">a template for marking messages that are likely to change in the near future (remember to remove it when the message stabilizes)</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Template:Logentry|logentry]]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">a template for marking log messages</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Template:Optional|optional]]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">a template for marking optional messages, which shouldn't be translated to most languages, and which aren't shown to translators by default</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Template:Ignored|ignored]]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">a template for marking ignored messages, which must not be translated at all</span>
;<code><nowiki>{{</nowiki>[[translatewiki:Template:Doc-important|doc-important]]<nowiki>}}</nowiki></code>
:<span lang="en" dir="ltr" class="mw-content-ltr">a template for emphasizing a paragraphs in the documentation.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">More templates of this kind can be found in the category [[:translatewiki:Category:Message Documentation Templates|Message Documentation Templates]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Have a look at the templates' pages for more information.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Internationalisation hints ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Besides [[#Message documentation|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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Even if only adding or editing messages in English, one should be aware of the needs of all languages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Each message is translated into more than 300 languages and this should be done in the best possible way.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Correct implementation of these hints will very often help you write better messages in English, too.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
[[Special:MyLanguage/Localisation#Help and contact info|Localisation#Help and contact info]] lists the main places where you can find the assistance of experienced and knowledgeable people regarding i18n.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Use message parameters and switches properly ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
That's a prerequisite of a correct wording for your messages.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Avoid message re-use ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The translators discourage message re-use.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This may seem counter-intuitive, because copying and duplicating code is usually a bad practice, but in system messages it is often needed.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">"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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">If you are adding multiple identical messages, please add message documentation to describe the differences in their contexts.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Don't worry about the extra work for translators.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Translation memory helps a lot in these while keeping the flexibility to have different translations if needed.</span>

{{anchor|Avoid patchwork messages}}
<div lang="en" dir="ltr" class="mw-content-ltr">
=== Avoid fragmented or "patchwork" messages ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Languages have varying word orders, and complex grammatical and syntactic rules.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Messages formed by multiple pieces of text, possibly with some indirection, also called "string concatenation", in code that cannot be directly controlled by translators, are called "lego" or "patchwork" messages in developers' jargon. It's practically impossible to translate "lego" messages correctly.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Make every message a complete phrase.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Several sentences can usually be combined much more easily into a text block, if needed.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Messages quoting each other ====
</div>
{{main|Manual:Messages API#Referring to other messages}}
<span lang="en" dir="ltr" class="mw-content-ltr">An exception from the rule may be messages referring to one another: 'Enter the original author's name in the field labelled <code><nowiki>{{int:name}}</nowiki></code> and click <code><nowiki>{{int:proceed}}</nowiki></code> when done'.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This makes the message consistent when a software developer or wiki operator alters the messages "name" or "proceed" later.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Without the int-trick, developers and operators would have to be aware of all related messages needing adjustment, when they alter one.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Write messages in natural language ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">As much as possible, write messages in natural, human language.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Try reading the message aloud and think: is this something that sounds like correct, grammatical English that humans ''speak''?</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If it's complex, hard to pronounce, or in any way unnatural in English, it will be even harder for translators and for users in other languages.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Avoid punctuation that is too technical or bureaucratic or that can't be read aloud.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Slash (<code>/</code>) should usually be replaced with "or".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">[[w:And/or|And/or]] should be replaced with "and" or "or".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Sentences with [[w:comma splice|comma splice]] should be split into shorter sentences.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Don't use terms and templates that are specific to particular projects ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki is used by very diverse people, within the Wikimedia movement and outside of it.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Even though it was originally built for an encyclopedia, it is now used for various kinds of content.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Therefore, use general terms.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Separate times from dates in sentences ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Some languages have to insert something between a date and a time which grammatically depends on other words in a sentence.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Thus, they will not be able to use date/time combined.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

=== Avoid <code><nowiki>{{SITENAME}}</nowiki></code> in messages ===
<span lang="en" dir="ltr" class="mw-content-ltr"><code><nowiki>{{SITENAME}}</nowiki></code> has several disadvantages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It can be anything (acronym, word, short phrase, ''etc.'') and, depending on language, may need the use of <code>{{ll|Manual:Messages_API#…on use context inside sentences via GRAMMAR|<nowiki>{{GRAMMAR}}</nowiki>}}</code> on each occurrence.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">No matter what, each message having <code><nowiki>{{SITENAME}}</nowiki></code> will need review in most wiki languages for each new wiki on which your code is installed.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In the majority of cases, when there is not a general <code>GRAMMAR</code> configuration for a language, wiki operators will have to add or amend PHP code so as to get <code><nowiki>{{GRAMMAR}}</nowiki></code> for <code><nowiki>{{SITENAME}}</nowiki></code> working.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This requires both more skills, and more understanding, than otherwise.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is more convenient to have generic references like "this wiki".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This does not keep installations from locally altering these messages to use <code><nowiki>{{SITENAME}}</nowiki></code>, but at least they don't have to, and they can postpone message adaption until the wiki is already running and used.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Avoid references to visual layout and positions ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">What is rendered where depends on skins.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Handheld devices, narrow windows, and so on may show blocks underneath each other, that would appear side-by-side on larger displays.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of visual layout.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.'').</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
MediaWiki does not support showing different messages or message fragments based on the current directionality of the interface (see [[phab:T30997|T30997]]).
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The upcoming browser and MediaWiki support for East and North Asian top-down writing<ref>http://dev.w3.org/csswg/css3-writing-modes/</ref> 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).
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Avoid references to screen colours ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of colour.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Thus, you should not refer to screen colours.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">(You should also not rely on colour alone as a mechanism for informing the user of state, for the same reason.)</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Avoid markup that doesn't need to be translated ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">HTML markup not requiring translation, such as enclosing {{tag|div|open}} tags, rulers above or below, and similar, should usually not be part of messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It's an unnecessary burden on translators, and is often accidentally altered or skipped in the translation process.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The translation interface has no syntax highlighting and limited validation, so mistakes are common.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Avoid complex wikitext markup as well.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Wikitext is sometimes terser than writing the same thing in PHP, and it's tempting to write something like:</span>

{{codesample-header|[[MediaWiki:Revreview-basic/en]]}}

<syntaxhighlight lang="wikitext">
This is the [[{{MediaWiki:Validationpage}}|stable version]], [{{fullurl:{{#Special:Log}}|type=review&page={{FULLPAGENAMEE}}}} checked] on <i>$2</i>.
[{{fullurl:{{FULLPAGENAMEE}}|oldid=$1&diff=cur}} $3 pending {{PLURAL:$3|change|changes}}] {{PLURAL:$3|awaits|await}} review.
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">However, this is difficult for translators, especially when translating to right-to-left languages, because parts of the message must remain in English, resulting in text direction changing many times in one line:</span>

{{codesample-header|[[MediaWiki:Revreview-basic/ar]]}}
<syntaxhighlight lang="wikitext" dir="rtl">
هذه هي [[{{MediaWiki:Validationpage}}|النسخة المستقرة]]، [{{fullurl:{{#Special:Log}}|type=review&page={{FULLPAGENAMEE}}}} المفحوصة] في <i>$2</i>.
[{{fullurl:{{FULLPAGENAMEE}}|oldid=$1&diff=cur}} {{PLURAL:$3||تغيير واحد معلق|تغييران معلقان|$3 تغييرات معلقة|$3 تغييرا معلقا|$3 تغيير معلق}}] {{PLURAL:$3||ينتظر|ينتظران|تنتظر|ينتظر}} المراجعة.
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">It's best to pass any link targets as message parameters, and use only simple markup like {{tmpl|0=<code>[$1 $2]</code>|$1|Label}} and {{tmpl|0=<code><nowiki>[[</nowiki>$1{{!}}Label<nowiki>]]</nowiki></code>|$1|Label}}.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Don't use the <code>formatnum</code> {{ll|Help:Magic words|magic word}} within messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Format the number parameters in the code that loads the message according to the instructions in {{ll|Manual:Messages API}}.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Translated messages are often longer than you think! ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Skimming foreign language message files, you almost never find translated messages shorter than Chinese ones and rarely shorter than English ones. However, you will often find translations that are much longer than English ones.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">Especially in forms, in front of input fields, English messages tend to be terse, and short.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">That is often not kept in translations.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Languages may lack the technical vocabulary present in English, and may require multiple words or even complete sentences to explain some concepts.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example, the brief English message "TSV file:" may have to be translated in a language as literally:</span>
<blockquote>''<span lang="en" dir="ltr" class="mw-content-ltr">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)</span>''</blockquote>
<span lang="en" dir="ltr" class="mw-content-ltr">This is, admittedly, an extreme example, but you get the trait.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span> :-(

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

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Basic words may have unforeseen connotations, or not exist at all ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">There are some words that are hard to translate because of their very specific use in MediaWiki.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Some may [[#Expect untranslated words|not be translated at all]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example, there is no word "user" relating to "someone who uses something" in several languages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Similarly, in [[:en:Colognian language|Kölsch]] the English words "namespace" and "apartment" translate the same word.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Also, in Kölsch, they say "corroborator and participant" in one word since any reference to "use" would too strongly imply "abuse".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.''.</span>

{{anchor|Expect untranslated words}}
=== Use {{tag|code|open}}, {{tag|var|open}}, and {{tag|kbd|open}} tags where needed ===
<span lang="en" dir="ltr" class="mw-content-ltr">When talking about technical parameters, values, or keyboard inputs, mark them appropriately as such using the HTML tags {{tag|code|open}}, {{tag|var|open}}, or {{tag|kbd|open}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Thus they are typographically set off form the normal text.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">That clarifies their sense to readers, avoiding confusion, errors and mis-representations.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Ensure that your message handler allows such markup.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Symbols, colons, brackets, ''etc.'' are parts of messages ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Many symbols are localisable, too. Some scripts have other kinds of brackets than the Latin script has.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">A colon may not be appropriate after a label or input prompt in some languages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Having those symbols included in messages helps to make better and less Anglo-centric translations, and also reduces code clutter.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
For example, there are different quotation mark conventions used in «Norwegian», ”Swedish”, »Danish«, „German”, and 「Japanese」.<ref>[[w:Quotation_mark#Summary_table]]</ref>
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If you need to wrap some text in localized parentheses, brackets, or quotation marks, you can use the <code>parentheses</code> {{int|parentheses}} or <code>brackets</code> {{int|brackets}} or <code>quotation-marks</code> {{int|quotation-marks}} messages like so:
</div>

<syntaxhighlight lang=php>
wfMessage( 'parentheses' )->rawParams( /* text to go inside parentheses */ )->escaped()
wfMessage( 'brackets' )->rawParams( /* text to go inside brackets */ )->escaped()
wfMessage( 'quotation-marks' )->rawParams( /* text to go inside quotation marks */ )->escaped()
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Do not expect symbols and punctuation to survive translation ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Ellipsis may be translated to "''etc.''", or to words.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Question marks, exclamation marks, colons will be placed other than at the end of a sentence, not at all, or twice.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">As a consequence, always include all of those in the text of your messages, and never try to insert them programmatically.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Use full stops ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">'''Do''' terminate normal sentences with full stops.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Use meaningful link anchors ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Make sure that the anchor describes the target page well.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Always avoid commonplace and generic words.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example, "Click here" is an absolute no-go,<ref>http://www.w3.org/QA/Tips/noClickHere</ref> since target pages are almost never about "click here".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Instead, Use precise action words telling what a user will get to when following the link, such as "You can [[Special:Upload|upload a file]] if you wish."</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
See also ''[http://www.nngroup.com/articles/using-link-titles-to-help-users-predict-where-they-are-going/ Help users predict where they are going]'', and [[w:Mystery meat navigation|mystery meat navigation]], and ''[https://tosbourn.com/click-here/ The main reasons why we shouldn't use click here as link text]''.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Avoid jargon and slang ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Avoid developer and power user jargon in messages. Try to use a simple language whenever possible.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Avoid saying "success", "successfully", "fail", "error occurred while", etc., when you want to notify the user that something happened or didn't happen.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">"The file was successfully renamed" -> "The file was renamed"</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">"File renaming failed" -> "There is a file with this name already. Please choose a different name."</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Be aware of whitespace and line breaks ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki's localised messages usually get edited within the wiki, either by wiki operations on live wikis, or by the translators on [[translatewiki.net]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You should be aware of how whitespace, especially at the beginning or end of your message, will affect editors:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">Spaces and line breaks (newlines) 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.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">There are some messages which require a space at the end, such as <code>word-separator</code> (which consists of just a space character in most languages).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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:</span><ref>
https://github.com/wikimedia/mediawiki/blob/REL1_34/includes/cache/MessageCache.php#L887
</ref>

* <code>&amp;#32;</code> – <span lang="en" dir="ltr" class="mw-content-ltr">space</span>
* <span lang="en" dir="ltr" class="mw-content-ltr"><code>&amp;nbsp;</code> or <code>&amp;#160;</code> – [[w:non-breaking space|non-breaking space]]</span>
* <span lang="en" dir="ltr" class="mw-content-ltr"><code>&amp;shy;</code> – [[w:soft hyphen|soft hyphen]]</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
On a related note, any other syntax elements affected by [[Special:MyLanguage/pre-save transforms|pre-save transforms]] also must not be used in messages, as they will be transformed when the message is edited on the wiki.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Use standard capitalisation ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Capitalisation gives hints to translators as to what they are translating, such as single words, list or menu items, phrases, or full sentences.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Correct (standard) capitalisation may also play a role in search engines' assessment of your pages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki uses [[w:Letter case|sentence case]] (''The quick brown fox jumps over the lazy dog'') in interface messages.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Therefore, don't use ALL-CAPS for emphasis.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Use CSS, or HTML {{tag|em|open}} or {{tag|strong|open}} per below:</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Emphasis ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">In normal text, [[w:Emphasis|emphasis]] like '''boldface''' or ''italics'' and similar should be part of message texts.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Local conventions on emphasis often vary, especially some Asian scripts have their own.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Translators must be able to adjust emphasis to their target languages and areas.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Try to use {{tag|em|open}} and {{tag|strong|open}} in your user interface to allow mark-up on a per language or per script basis.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">In modern screen layouts of English and European styles, emphasis has become used less.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Do convey it in your [[#Message documentation|#Message documentation]] still, as it may give valuable hints as to how to translate.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Emphasis can and should be used in other cultural contexts as appropriate, provided that translators know about it.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Some things must be added to English messages even when they are not required ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">It sometimes happens that English messages don't need some $ parameters or PLURAL or GENDER support, but translations of those messages into other languages do need them.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In such cases, these parameters or keywords must be added to English, even if they don't do anything.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">This is necessary for two reasons:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">It clearly shows the translator within the message that those parameters are available.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">It prevents translatewiki from showing warnings about parameters that are used in the translation, but aren't used in English.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">For example, the English word "deleted" may refer to one deleted page or to several deleted pages, but in other languages the word would be different depending on the number of pages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">So write something like this: <code><nowiki>{{PLURAL:$1|deleted}}</nowiki></code>.</span>

<span id="See_also"></span>
== دا هم وگورئ ==
* {{ll|Customization}}
* {{ll|Manual:Configuration settings}}
* {{ll|Manual:Skins}}
* {{ll|Manual:Messages API}}
* {{ll|Localisation}}
* {{ll|Manual:MediaWiki architecture#Localizing messages|2=<span lang="en" dir="ltr" class="mw-content-ltr">Manual:MediaWiki architecture and Localizing messages</span>}}
* [[translatewiki:FAQ]]

<div lang="en" dir="ltr" class="mw-content-ltr">
== Notes ==
</div>
<references />

[[Category:Customization techniques{{#translation:}}]]
[[Category:User interface{{#translation:}}]]
[[Category:Localisation{{#translation:}}]]
[[Category:System message{{#translation:}}]]
[[Category:Help{{#translation:}}|{{PAGENAME}}]]