English messages almost never need different words that change because of a user's gender.English only needs this in the third-person pronouns "he" and "she", but these are surprisingly rare in messages.When this is necessary, use he or they.
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.It is therefore often useful to use GENDER in English messages, even when there's only English word.This gives translators a hint that GENDER can be used in a message.It also avoids warnings on translatewiki about missing parameters when an optional username parameter is missing (this happens especially often in log entry messages).
如果translatewiki.net支持扩展,请仅更改英文源消息和/或密钥,以及qqq.json中的附带条目。 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.
Besides documentation, translators ask developers to consider some hints so as to make their work easier and more efficient and to allow an actual and good localisation for all languages.Even if only adding or editing messages in English, one should be aware of the needs of all languages.Each message is translated into more than 300 languages and this should be done in the best possible way.Correct implementation of these hints will very often help you write better messages in English, too.
Localisation#Help_and_contact_info lists the main places where you can find the assistance of experienced and knowledgeable people regarding i18n.
Use message parameters and switches properly
That's a prerequisite of a correct wording for your messages.
Avoid message re-use
The translators discourage message re-use.This may seem counter-intuitive, because copying and duplicating code is usually a bad practice, but in system messages it is often needed.Although two concepts can be expressed with the same word in English, this doesn't necessarily mean they can be expressed with the same word in every language."OK" is a good example: in English this is used for a generic button label, but in some languages they prefer to use a button label related to the operation which will be performed by the button.Another example is practically any adjective: a word like "multiple" changes according to gender in many languages, so you cannot reuse it to describe several different things, and you must create several separate messages.
If you are adding multiple identical messages, please add message documentation to describe the differences in their contexts.Don't worry about the extra work for translators.Translation memory helps a lot in these while keeping the flexibility to have different translations if needed.
Avoid fragmented or "patchwork" messages
Languages have varying word orders, and complex grammatical and syntactic rules.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.
Make every message a complete phrase.Several sentences can usually be combined much more easily into a text block, if needed.When you want to combine several strings in one message, pass them in as parameters, as translators can order them correctly for their language when translating.
An exception from the rule may be messages referring to one another: 'Enter the original author's name in the field labelled "{{int:name}}" and click "{{int:proceed}}" when done'.This makes the message consistent when a software developer or wiki operator alters the messages "name" or "proceed" later.Without the int-trick, developers and operators would have to be aware of all related messages needing adjustment, when they alter one.
Write messages in natural language
As much as possible, write messages in natural, human language.
Try reading the message aloud and think: is this something that sounds like correct, grammatical English that humans speak?
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.
Avoid punctuation that is too technical or bureaucratic or that can't be read aloud.
Slash (/) should usually be replaced with "or".
And/or should be replaced with "and" or "or".
Sentences with comma splice should be split into shorter sentences.
Don't use terms and templates that are specific to particular projects
MediaWiki is used by very diverse people, within the Wikimedia movement and outside of it.Even though it was originally built for an encyclopedia, it is now used for various kinds of content.Therefore, use general terms.For example, avoid terms like "article", and use "page" instead, unless you are absolutely sure that the feature you are developing will only be used on a site where pages are called "articles".Don't use "village pump", which is the name of an English Wikipedia community page, and use a generic term, such as "community discussion page", instead.
Don't assume that a certain template exists on all wikis.Templates are local to wikis.This applies to both the source messages and to their translations.If messages use templates, they will only work if a template is created on each wiki where the feature is deployed.It's best to avoid using templates in messages completely.If you really have to use them, you must document this clearly in the message documentation and in the extension installation instructions.
Separate times from dates in sentences
Some languages have to insert something between a date and a time which grammatically depends on other words in a sentence.Thus, they will not be able to use date/time combined.Others may find the combination convenient, thus it is usually the best choice to supply three parameter values (date/time, date, time) in such cases, and in each translation leave either the first one or last two unused as needed.
Avoid {{SITENAME}} in messages
{{SITENAME}} has several disadvantages.It can be anything (acronym, word, short phrase, etc.) and, depending on language, may need the use of {{GRAMMAR}} on each occurrence.No matter what, each message having {{SITENAME}} will need review in most wiki languages for each new wiki on which your code is installed.In the majority of cases, when there is not a general GRAMMAR configuration for a language, wiki operators will have to add or amend PHP code so as to get {{GRAMMAR}} for {{SITENAME}} working.This requires both more skills, and more understanding, than otherwise.It is more convenient to have generic references like "this wiki".This does not keep installations from locally altering these messages to use {{SITENAME}}, but at least they don't have to, and they can postpone message adaption until the wiki is already running and used.
Avoid references to visual layout and positions
What is rendered where depends on skins.Most often screen layouts of languages written from left-to-right are mirrored compared to those used for languages written from right-to-left, but not always, and for some languages and wikis, not entirely.Handheld devices, narrow windows, and so on may show blocks underneath each other, that would appear side-by-side on larger displays.Since site- and user-written JavaScript scripts and gadgets can, and do, hide parts, or move things around in unpredictable ways, there is no reliable way of knowing the actual layout.
It is wrong to tie layout information to content languages, since the user interface language may not be the page's content language, and layout may be a mixture of the two depending on circumstances.Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of visual layout.Thus, you should not refer to visual layout positions in the majority of cases, though semantic layout terms may still be used ("previous steps in the form", etc.).
MediaWiki does not support showing different messages or message fragments based on the current directionality of the interface (see T30997).
The upcoming browser and MediaWiki support for East and North Asian top-down writing[2] will make screen layouts even more unpredictable, with at least eight possible layouts (left/right starting position, top/bottom starting position, and which happens first).
Avoid references to screen colours
The colour in which something is rendered depends on many factors, including skins, site- and user-written JavaScript scripts and gadgets, and local user agent over-rides for reasons of accessibility or technological limitations.Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of colour.Thus, you should not refer to screen colours.(You should also not rely on colour alone as a mechanism for informing the user of state, for the same reason.)
Avoid untranslated HTML markup in messages
HTML markup not requiring translation, such as enclosing <div> tags, rulers above or below, and similar, should usually not be part of messages.They pose security risks, unnecessarily burden translators, increase message file size, and can accidentally being altered or skipped in the translation process.In general, avoid raw HTML in messages if you can.
Translated messages are often longer than you think!
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.
Especially in forms, in front of input fields, English messages tend to be terse, and short.That is often not kept in translations.Languages may lack the technical vocabulary present in English, and may require multiple words or even complete sentences to explain some concepts.For example, the brief English message "TSV file:" may have to be translated in a language as literally:
Please type a name here which denotes a collection of computer data that is comprised of a sequentially organised series of typewritten lines which themselves are organised as a series of informational fields each, where said fields of information are fenced, and the fences between them are single signs of the kind that slips a typewriter carriage forward to the next predefined position each. Here we go: _____ (thank you)
This is, admittedly, an extreme example, but you get the trait.Imagine this sentence in a column in a form where each word occupies a line of its own, and the input field is vertically centered in the next column. :-(
Avoid using very close, similar, or identical words to denote different things, or concepts
For example, pages may have older revisions (of a specific date, time, and edit), comprising past versions of said page.The words revision, and version can be used interchangeably.A problem arises, when versioned pages are revised, and the revision, i.e. the process of revising them, is being mentioned, too.This may not pose a serious problem when the two synonyms of "revision" have different translations.Do not rely on that, however.It is better to avoid the use of "revision" aka "version" altogether, then, so as to avoid it being misinterpreted.
Basic words may have unforeseen connotations, or not exist at all
There are some words that are hard to translate because of their very specific use in MediaWiki.Some may not be translated at all.For example, there is no word "user" relating to "someone who uses something" in several languages.Similarly, in Kölsch the English words "namespace" and "apartment" translate the same word.Also, in Kölsch, they say "corroborator and participant" in one word since any reference to "use" would too strongly imply "abuse".The term "wiki farm" is translated as "stable full of wikis", since a single-crop farm would be a contradiction in terms in the language, and not understood, etc..
Use <code>, <var>, and <kbd> tags where needed
When talking about technical parameters, values, or keyboard inputs, mark them appropriately as such using the HTML tags <code>, <var>, or <kbd>.Thus they are typographically set off form the normal text.That clarifies their sense to readers, avoiding confusion, errors and mis-representations.Ensure that your message handler allows such markup.
Symbols, colons, brackets, etc. are parts of messages
Many symbols are localisable, too. Some scripts have other kinds of brackets than the Latin script has.A colon may not be appropriate after a label or input prompt in some languages.Having those symbols included in messages helps to make better and less Anglo-centric translations, and also reduces code clutter.
For example, there are different quotation mark conventions used in «Norwegian», ”Swedish”, »Danish«, „German“, and “Japanese”.[3]
If you need to wrap some text in localized parentheses, brackets, or quotation marks, you can use the parentheses ($1) or brackets [$1] or quotation-marks "$1" messages like so:
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()
Do not expect symbols and punctuation to survive translation
Languages written from right to left (as opposed to English) usually swap arrow symbols being presented with "next" and "previous" links, and their placement relative to a message text may, or may not, be inverted as well.Ellipsis may be translated to "etc.", or to words.Question marks, exclamation marks, colons will be placed other than at the end of a sentence, not at all, or twice.As a consequence, always include all of those in the text of your messages, and never try to insert them programmatically.
Use full stops
Do terminate normal sentences with full stops.This is often the only indicator for a translator to know that they are not headlines or list items, which may need to be translated differently.
Link anchors
Wikitext of links
Link anchors can be put into messages in several technical ways:
via wikitext:
… [[a wiki page|anchor]] …,
via wikitext:
… [some-urlanchor] …
the anchor text is a message in the MediaWiki namespace. Avoid it!
The latter is often hard or impossible to handle for translators, avoid fragmented or 'patchwork' messages here, too.Make sure that "some-url" does not contain spaces.
Use meaningful link anchors
Take care with your wording.Link anchors play an important role in search engine assessment of pages – both the words linked, and the target anchor.Make sure that the anchor describes the target page well.Always avoid commonplace and generic words.For example, "Click here" is an absolute no-go,[4] since target pages are almost never about "click here".Do not put that in sentences around links either, because "here" was not the place to click.Instead, Use precise action words telling what a user will get to when following the link, such as "You can upload a file if you wish."
Avoid developer and power user jargon in messages. Try to use a simple language whenever possible.Avoid saying "success", "successfully", "fail", "error occurred while", etc., when you want to notify the user that something happened or didn't happen.This comes from developers' perspective of seeing everything as true or false, but users usually just want to know what actually happened or didn't, and what they should do about it (if at all). So:
"The file was successfully renamed" -> "The file was renamed"
"File renaming failed" -> "There is a file with this name already. Please choose a different name."
Be aware of whitespace and line breaks
MediaWiki's localised messages usually get edited within the wiki, either by wiki operations on live wikis, or by the translators on translatewiki.net.You should be aware of how whitespace, especially at the beginning or end of your message, will affect editors:
Spaces and line breaks (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.
Spaces and line breaks at the beginning are not automatically removed, but they are likely to be removed by accident during editing, and should be avoided.
Start and end your message with active text; if you need a newline or paragraph break around it, your surrounding code should deal with adding it to the returned text.
There are some messages which require a space at the end, such as 'word-separator' (which consists of just a space character in most languages).To support such use cases, the following HTML entities are allowed in messages and transformed to the actual characters, even if the message otherwise doesn't allow wikitext or HTML formatting:[5]
On a related note, any other syntax elements affected by pre-save transforms also must not be used in messages, as they will be transformed when the message is edited on the wiki.
Use standard capitalisation
Capitalisation gives hints to translators as to what they are translating, such as single words, list or menu items, phrases, or full sentences.Correct (standard) capitalisation may also play a role in search engines' assessment of your pages.MediaWiki uses sentence case (The quick brown fox jumps over the lazy dog) in interface messages.
Always remember that many writing systems don't have capital letters at all, and some of those that do have them, use them differently from English.Therefore, don't use ALL-CAPS for emphasis.Use CSS, or HTML <em> or <strong> per below:
Emphasis
In normal text, emphasis like boldface or italics and similar should be part of message texts.Local conventions on emphasis often vary, especially some Asian scripts have their own.Translators must be able to adjust emphasis to their target languages and areas.Try to use "<em>" and "<strong>" in your user interface to allow mark-up on a per language or per script basis.
In modern screen layouts of English and European styles, emphasis becomes less used.Do convey it in your #Message documentation still, as it may give valuable hints as to how to translate.Emphasis can and should be used in other cultural contexts as appropriate, provided that translators know about it.