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 translatewiki.net, 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.

Summary:

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 translatewiki.net

• 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: https://etherpad.wikimedia.org/p/vCX44XEHpyxvKG7cwhrv

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.

In T293776#7508484, @TBurmeister wrote:

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 translatewiki.net, 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 https://www.mediawiki.org/wiki/Translator_hub (as that is linked from https://www.mediawiki.org/wiki/How_to_contribute ).

Today @Nikerabbit and I did the following:

• Reviewed revised landing page sections in https://bit.ly/3nLaCVN
• 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 translatewiki.net
• 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
• translatewiki.net 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

Early draft to test new layout is started here https://www.mediawiki.org/wiki/User:TBurmeister_(WMF)/Sandbox/Localisation

Final draft of what the new Localisation landing page will look like is now live at https://www.mediawiki.org/wiki/User:TBurmeister_(WMF)/Sandbox/Localisation. 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
  • translatewiki.net (the page on mediawiki.org, 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.

In T293776#7527079, @TBurmeister wrote:

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.

In T293776#7563536, @Aklapper wrote:

(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

In T293776#7565176, @Tacsipacsi wrote:

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