Page MenuHomePhabricator

Review localization landing page
Closed, ResolvedPublic


This task is part of a project to establish a formal review process and set of standards for Wikimedia technical documentation. For more information, visit the project page on


Content review

What is the topic of the page?

  • MediaWiki internationalisation and localisation (i18n and L10n)

Does the page fit into to a defined content type?

  • It wants to be a landing page but is including tons of information that is more like a reference for developers

What information is included on the page?

  • Technical aspects of MediaWiki's internationalisation and localisation (i18n and L10n) system and philosophy
  • "How to get things localized": tidbits about and links to Localisation overview and other guides. How to find the messages you want to localize.
  • "How to stay updated about i18n stuff": link to mailing list. Seems odd at its current location.
  • "Conceptual overview of language objects": structure of messages, Localisation file format
  • "How to work with messages": do's and don'ts of interacting with message keys and parameters. Buried link to "VERY IMPORTANT API DOC":Manual:Messages API. "This is an important documentation page, and you should read it before you write code that uses messages." Buried link in translatewiki section to
  • "Understanding things from translators' POV and how to make your messages nice for them": how to document your messages and provide i18n hints (?) to help with translation. Some things are "suggested guidelines, not standard in MediaWiki development" -- which makes me wonder where is there a list of the things that *are* standard and that developers *must* do or follow? Much of the "Internationalisation hints" section reads like an unordered list of points of confusion that have arisen between the users of the translation system (translators) and developers. It sounds important to clearly articulate (within the API documentation?) how some of these code decisions / developer behaviors ultimately impact the translators -- rather than just having this large list of "hints".
  • Interacting with translators (how to handle support requests on translatewiki)
  • Conceptual overview of how localization works (Note: this section and below feels like what used to be the old contents of the page, and everything above is organic growth over time / cruft)
  • System details about messages and caching implementation
  • Reference list of "things that can be translated"
  • Information about the old translation system

Who is the audience (or audiences) of the page? Is the content of the page suitable for that audience?

  • MediaWiki developers who want to translate elements of MediaWiki, extensions and skins

Are there any duplicate pages or overlapping content that needs to be merged or marked as obsolete?

  • The "Overview of the localisation system" should be its own doc that provides a more gentle introduction to how things work, without all of the technical / system architecture details. There may be other overviews, too; see "links" section below.
  • The sections on "Message sources", "caching", "code structure" and "language objects" should be an explanatory document that has some diagrams to help developers create a mental model of the architecture.
  • The sections about "Using messages" (and all the other types of actions you do with them) and how to interact with / work effectively with translators should be separate user guides, with key hints and guidelines integrated into the API documentation so that developers are more likely to see them and follow the best practices when they're writing code.

How is the page linked to related pages? What categories does the page belong to? Is it part of a clearly defined collection of pages? Check Special:PrefixIndex for subpages.

i18n template includes links to: Localisation (this page); System message; Messages API; Language;; Writing systems; Directionality
TODO (more to review, but all the following docs have overlap with some of the content on the Localisation landing page):

  • Important links that are somewhat buried in body text:

"How to get things localized":

  • Overview of the localisation system (an introduction that is buried at the bottom of the page)
  • What can be localised (a section of reference content that is linked at the top but buried at the bottom of the page)

"How to work with messages": Buried link to "VERY IMPORTANT API DOC":Manual:Messages API. "This is an important documentation page, and you should read it before you write code that uses messages." But apparently you should also read the stuff on this page because it has important tips. Are they also represented in the Messages API documentation? Let's go find out! (later). Buried link in translatewiki section to

"How to stay informed about i18n stuff"

  • some content at the top in the translatewiki section, more buried below in the "internationalisation" section ("These are the main places where you can find the assistance of experienced and knowledgeable people regarding i18n: The support page of The #translatewiki connect IRC channel. Please do ask there!")

To review: translatewiki:Translating:Localisation for developers. - is this yet another localisation landing page? how does its content differ from what's here?
To review: translatewiki:Translating:MediaWiki

Event Timeline

TBurmeister changed the task status from Open to In Progress.Oct 26 2021, 9:44 PM
TBurmeister triaged this task as Medium priority.

Question: to what extent are translators a potential audience of this doc? Should there be a set of links for them, or a redirect to, or is that not even necessary?

My recommendations for this page are, at a high-level:

  1. Move all the content from the Localisation landing page into other core docs in the i18n collection.
  2. Improve the utility of the Localisation landing page (and bring it into alignment with criteria for cross-collection landing pages) by building out a link hub layout that directs readers to those core docs.

This Google Doc explains the proposal in detail. This spreadsheet lists where each section of the landing page content could move.


I propose the Localisation landing page include the following sections and content in a link hub layout:

Language in MediaWiki

  • Code structure
  • What are language objects?
  • Get and/or set the language for an object
  • Convert language objects into different scripts
  • Support different directionality

System messages and documentation

  • What are system messages?
  • Find system messages
  • Add system messages
  • Follow best practices
  • Document messages for translation
  • Change or delete messages

Localise messages with

  • Install Extension:Translate
  • Start or manage translation projects
  • Follow best practices
  • Respond to support requests from translators
  • I want to localize…
  • - Page content
  • - Site content
  • - UI text
  • - Namespaces
  • - Special page aliases
  • - Time and date formats
  • - MediaWiki Action API messages
  • … -> what can be localised

Use MediaWiki messages in your code

  • Find system messages
  • Get the language of an object
  • Use messages in PHP
  • Use messages in JavaScript
  • Use messages in Lua
  • Work with gender, grammar, and plurals

Get help (mailing list, other contact channels)

Content that currently resides on the landing page and is being moved into the "core pages" should be reviewed and updated according to the content and style checklists for this project; other updates to these docs are out of scope for now. The Google Doc and this spreadsheet outline all of the above and the specifics of all the changes this will involve to these docs, if maintainers and stakeholders agree with the plan.

Chatted with @Nikerabbit, he shared this quick outline of his mental model of these docs:

I'll review this and iterate on the landing page link hub content I'm proposing, with the goal of us syncing up on this and identifying next steps in a meeting next week.

Question: to what extent are translators a potential audience of this doc? Should there be a set of links for them, or a redirect to, or is that not even necessary?

I'd probably add a hatnote (?) that the page is for developers how to make user visible strings in code translatable to other human languages, and if you want to translate strings from English to another language, see (as that is linked from ).

Today @Nikerabbit and I did the following:

  • Reviewed revised landing page sections in
  • Decided it's worthwhile having a box with links for translators to help redirect them to translatewiki docs, but also to ULS extension content relevant to them
  • Discussed the plan for which content from the landing page will go into the other docs (as outlined in spreadsheet)
  • Decided that most of the "internationalisation hints" should stay in the l10n docs and not move into Manual:Coding_conventions#System_messages
  • Discussed if there are any additional topics to consider building into the landing page link hub

The revised link hub sections that I'll be implementing are listed below. They will be subject to further review and improvement, but this will be v0:

For translators:

  • Translate MediaWiki interface messages
  • Write a new article using Content Translation
  • Language names reference
  • language search, plural definitions…
  • How to input text in different scripts (IMEs)
  • Download and enable different webfonts
  • Universal Language Selector FAQ

For developers:

Get your code translated

  • Use
  • What can be localised

Write code that can be localised

  • Overview of language in MediaWiki
  • i18n features (namespaces, time and date formats, fallbacks)
  • Write system messages
  • Write good i18n code
  • Directionality support

Implement a multilingual wiki

  • MediaWiki language extension bundle
  • Translate extension
  • Universal Language Selector (ULS) extension
  • Writing systems support
  • Multilingual semantic MediaWiki
  • Content translation (CX) extension
  • Customize messages in your local wiki

Add a wiki in a new language

Get help

  • mediawiki-i18n mailing list
  • Support page
  • #translatewiki connect IRC channel
  • Find translators for your language
  • File a bug
  • Language Engineering team

Next steps for this task

  1. Implement landing page changes
  2. Complete content review and make any updates
  3. Complete style review and make updates

Final draft of what the new Localisation landing page will look like is now live at Not all of the links work because many of them rely on content having been moved to its new home. This is just to have a visual reference for feedback before I start destroying the real page.

(On an unrelated note, the rewrite will inevitably break some anchor links out there (I just fixed one here and one here), and I am not aware of any way to find them...)

I have completed the following:

  • Implemented link hub layout on the Localisation landing page and verified that all its links work
  • Moved all non-navigational content off the landing page and into other pages in the i18n collection (map of what went where)
  • Checked all anchor links in the following docs for the content I moved:
    • Help:System_message
    • Manual:Language
    • (the page on, not the entire translate wiki)
    • Manual:Messages_API
    • Writing_systems
    • Directionality_support
  • Updated the GRAMMAR redirect page to re-direct to the appropriate new content location
  • Integrated content from Localisation_file_format into Help:System_message; added a redirect

I have attempted to put the content in some sort of order that makes sense, but all of these docs need a thorough content review and style updates to improve their utility and readability. Especially Help:System_message, since it is now the home of the large list of "Internationalisation hints". That type of doc update is out of scope for this task, but I did document much of what needs to be done in the Google doc. There are also some TODOs in the wikitext (some from me, some pre-existing.)

I'm going to remove the Donottranslate template from all the pages except the Localisation landing page, since we don't yet have a timeline for making additional content updates and I wouldn't want them to stay un-translated. So, the work that remains for this task is:

  • Go through the content review checklist now that the Localisation landing page meets our criteria for landing pages
  • Complete style review and any style updates for Localisation landing page
  • Use any available tools and strategies to try to fix broken links in any other high traffic docs that were linking to content that I moved.

For developers:

Get your code translated


Write code that can be localised

Why in this order? One first writes code that can be localised, and after that does one get the code actually localised. I suggest swapping the two boxes.

(On an unrelated note, the rewrite will inevitably break some anchor links out there (I just fixed one here and one here), and I am not aware of any way to find them...)

Links using {{ll}} should be visible on Special:WhatLinksHere. With that list in hand, a bot can go through it, load the raw wikitext after template expansion (action=raw&templates=expand) and use a regex to determine whether the link is a broken anchor link. For links not using {{ll}}, unfortunately there’s no backlink tracking, so our best try is a regex wiki search (and then going through the results similarly to the Special:WhatLinksHere case).

@Tacsipacsi, I agree with your comment about the order of the boxes; I just switched them. And thanks for the regex wiki search you shared to look for broken links!

Content checklist

  • Title style: Uses sentence case for titles. The title should be descriptive and specific. This helps visitors decide whether they would want to use the page. For example: "Accessing Instances on Cloud VPS" is much better than "Instances".
  • Introduction: For search optimization and page previews, include a short introduction as the first text on the page following the title. This should briefly introduce the content type, purpose of the page, general audience, and topic with the goal of providing enough information to be meaningful in a set of search results.
  • Table of contents: MediaWiki automatically creates a table of contents when a page has more than three headings.[1] Use template:TOC to limit the heading levels displayed in the table of contents so that it is meaningful and concise. To save space, a table of contents can be opposite the title (right-aligned in LTR languages).
  • Section headings: Section headings use sentence case. Headings should use h2, h3, and h4 styles.
  • Code samples: Code samples should use template:Codesample and include a filename if appropriate.
  • n/a
  • Links: Links on the page go to existing, non-obsolete pages (unless for historical reasons). Link text is descriptive and does not include any wiki prefixes. Special:MyLanguage links are used whenever possible.
  • Lists: Do not use bulleted list items to complete an introductory sentence fragment.
  • Status: No draft or outdated banners are present.
  • Feedback and communication: The page prompts readers to share feedback or ask a question. It indicates where readers can go to get updates or connect with others, if appropriate. A talk page exists (or redirects to a central talk page) with at least a welcome post.
  • Translation: If translation is available and the content of the page is stable, the page is marked for translation.
  • Mobile: The page is readable on mobile, with all important information visible.
  • Accessibility: The page complies with the accessibility guide for developers.
    • Checked this using WAVE
  • Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).
    • n/a
  • Descriptive title: Because landing pages help organize and contextualize other pages, the title of a landing page should be descriptive enough to make sense when viewed directly from a search engine.
  • Image: If possible, include an image relevant to the topic, such as a project logo. The image can be centered or aligned opposite the title (right-aligned in LTR languages) using [[File:Example|{{dir|{{pagelang}}|left|right}}|30x30px]][2].
    • n/a
  • Topic overview: To provide context, a landing page should include a section that introduces the topic or theme of the page. For example, a landing page for Toolforge should include a section that describes what Toolforge is, what is does, and who uses it. This can be under an "About Toolforge" section or, if it makes sense with the layout of the page, in the first section under the title.
  • Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.[3]
  • Link hub layout: When linking to other documentation pages, present groups of links in a way that is easy to navigate, such as Template:ContentGrid, Template:Colored box, Template:Contribution, Template:Portal list item on Wikitech, or a sidebar. Avoid organizing links with tables or headings.
  • Maintainer resources: Landing pages help facilitate the maintenance of a set of documentation. If possible, include ways for people to participate by subscribing to updates, watching pages, joining editathons, etc. Be explicit about which pages to watch to help answer questions and monitor edits.
  • Navigation between subpages: A landing page should include a navigation element that allows readers to move between pages within the collection, such as a sidebar, navigation box, or set of tabs. If the collection is organized using subpages, include a prefix search box.

Writing style review

  • Plain language: The language used on the page is clear and concise. It is free of jargon, idioms, and other ambiguous or confusing elements. Sentences are not more than 30 words in length.
  • Positive language: Avoid using negative sentence constructions.
  • Inclusive language: Use non-gendered language, and avoid the terms listed in the inclusive language guide.
  • Active voice: Use active voice, except when diplomacy calls for passive voice.
  • Second person point of view: Uses second person ("You" or assumed "You") when addressing your audience. Avoid first person ("I", "we", "our"), unless the page is an FAQ with questions asked from the first person perspective.
  • Imperative mood: Uses an imperative mood for most documentation focused on goals or process. Avoid future tense ("will").
  • Typos: The page has been reviewed for typos.
  • (Optional) Grade level check: Use a writing analysis tool (like Expresso) to check the grade level of the page (sometimes called a readability score). Strive to keep documentation under an eighth grade reading level.
    • Grade before (and after) style revisions: 22.5

so our best try is a regex wiki search (and then going through the results similarly to the Special:WhatLinksHere case).

@Tacsipacsi: Big thanks! I hope I fixed all of them (12 broken anchor links in total).