Page MenuHomePhabricator
Create Task
Maniphest T391616

Update documentation for working with translated pages on wiki
Closed, ResolvedPublic
Actions

Description

Contributors to technical documentation on mediawiki.org and Meta-Wiki are often editing pages with Translate extension markup. Although great for translators, this markup is difficult to understand and edit confidently, even after a diligent reading of the docs. This project aims to review the available documentation for working with translation markup, consolidate the sources of information that have naturally grown over time, and update the content with the latest recommended guidance.

Target completion date: June 27, 2025
Actual completion date: June 27, 2025

Outcomes

I updated the key documentation pages for working with translation markup to reflect best practices and include examples of key use cases:

  • Translation extension reference on mediawiki.org (before, after, diff): Comprehensive reference for working with translation markup and translated pages. Focuses on the capabilities of the Translate extension more than conventions on any one wiki.
  • Internationalization guidelines on Meta-Wiki (before, after, diff): Shorter, easier-to-read guide to working with translation markup. Focuses specifically on conventions used on Wikimedia wikis, although it's important to note that these conventions differ between wikis due to differences in preference between translation administrator communities.

I found that the key tutorial on mediawiki.org uses a significantly different approach than I wanted to use. It focuses on a simplified version of translation markup, uses Wikipedia-like examples, and takes an iterative approach to adding and marking content. Because this tutorial is well established, has significant pageviews, and is extensively translated, I chose not to suggest radically revising the tutorial. Instead, I posed a question on the talk page on whether the tutorial should be evolved to reflect less simplified methods that are closer to widely used best practices. As an alternative, I published a new tutorial on Meta-Wiki that uses a wider range of examples and focuses on marking an entire page for translation using conventions used on Wikimedia wikis.

I started this project with the goal of consolidating the various pages related to translation markup into a few key pages. However, as I researched the content, I found that this was unrealistic. Because translation markup is a complicated subject, there are many different ways to approach explaining it, and there will always be people creating new tutorials and guides for how to use it. Instead of discouraging these efforts, it's better to ensure that these various related pages all link back to the key reference pages on mediawiki.org and Meta-Wiki (listed above). As part of this project, I updated all pages related to translation markup that I could find to link back to these key pages.

Goals

Scope

Use cases in scope:

Use cases out of scope:

  • Marking pages for translation and other translation admin tasks
  • Translating content
  • Deciding whether to translate a page
    • I decided not to add any further guidance other than waiting for content to stabilize. Any content on a multilingual wiki can be marked for translation. If the audience of a page is limited to an English audience, it should be moved to Wikitech. See Find docs.

Project plan

Approach

With a complex topic like translation markup, there are many different ways to present the information, and there will always be people creating new pages to explain how to use it. Instead of trying to delete or redirect these various pages, I think it would be more productive to focus on keeping a few key pages up to date and ensuring that additional pages link back to those sources.

Key pages for Translation extension documentation as applies to any wiki that uses it:

Key page with supplementary information about conventions specific to Wikimedia wikis:

This project focused on making these three pages as accurate and usable as possible, and then adding links to these pages from other pages related to translation markup.

Content audit

Content types:

  • explanation
  • tutorial
  • examples

Scopes:

  • Translate extension used on any wiki
  • Wikimedia wikis
    • mediawiki.org
    • Meta-Wiki
    • Foundation Wiki
    • Outreach Wiki
    • Wikispecies
    • Wikidata
    • Wikimania
    • Incubator
    • Likely others

Pages:

Pageviews:

Use cases

Links

  • Link to a page on the same wiki
  • Link to a page on another wiki
  • Link to a page outside a wiki
  • Link to Wikipedia
  • Link within a sentence
  • Link outside a sentence
  • Use custom link text
  • Link to a section
  • Link to a section on another page
  • Omit the namespace from the link text

Questions:

Draft: https://www.mediawiki.org/wiki/User:APaskulin_(WMF)/Sandbox/Translation#Links

Code samples

  • Code samples in a sentence
  • Code sample blocks
  • Comments in code samples

Draft: https://www.mediawiki.org/wiki/User:APaskulin_(WMF)/Sandbox/Translation#Code_samples

Templates and transclusion

  • Templates without translatable parameters
  • Templates with translatable parameters
  • Transclude a translated page

Draft: https://www.mediawiki.org/wiki/User:APaskulin_(WMF)/Sandbox/Translation#Templates_and_transclusion

Lists

  • Ordered lists
  • Unordered lists

Draft: https://www.mediawiki.org/wiki/User:APaskulin_(WMF)/Sandbox/Translation#Lists

Event Timeline

apaskulin created this task.Apr 10 2025, 6:07 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptApr 10 2025, 6:07 PM
apaskulin moved this task from Backlog to Active projects on the Tech-Docs-Team board.Apr 10 2025, 6:07 PM
apaskulin updated the task description. (Show Details)Apr 11 2025, 12:08 AM
apaskulin updated the task description. (Show Details)Apr 11 2025, 12:10 AM
Aklapper awarded a token.Apr 11 2025, 3:43 AM
Aklapper added a comment.Apr 11 2025, 3:47 AM

Side note: I think translatetagger.toolforge.org isn't mentioned anywhere currently, might be something to consider after T391651 got resolved.

Pppery subscribed.Apr 11 2025, 4:32 AM
KBach awarded a token.Apr 11 2025, 6:32 AM
KBach subscribed.
TBurmeister subscribed.Apr 11 2025, 3:21 PM

A couple additional docs that may be in scope or have useful information to include in revised docs:

apaskulin updated the task description. (Show Details)Apr 15 2025, 10:21 PM
apaskulin updated the task description. (Show Details)Apr 24 2025, 10:47 PM
A_smart_kitten subscribed.Apr 28 2025, 9:09 AM
apaskulin updated the task description. (Show Details)May 1 2025, 11:51 PM
apaskulin updated the task description. (Show Details)May 8 2025, 11:34 PM
apaskulin updated the task description. (Show Details)May 15 2025, 11:02 PM
apaskulin updated the task description. (Show Details)May 22 2025, 11:15 PM
apaskulin updated the task description. (Show Details)May 29 2025, 11:56 PM
apaskulin updated the task description. (Show Details)Jun 13 2025, 12:25 AM
apaskulin added a comment.Jun 13 2025, 12:28 AM

This week I completed the draft of the new translation tutorial. I originally planned to propose this as a replacement to the existing tutorial on mediawiki.org, but I ultimately decided to publish is as a new subpage of https://meta.wikimedia.org/wiki/Meta:Internationalization_guidelines. This is because the mediawiki.org tutorial is already well established and well used. Instead, I'll be making iterative improvements to the existing tutorial to improve usability. I started these updates this week; see the recent updates to the task description for edit links.

apaskulin updated the task description. (Show Details)Jun 19 2025, 9:52 PM
apaskulin added a comment.Jun 19 2025, 10:18 PM

This week, I published the new tutorial to https://meta.wikimedia.org/wiki/Meta:Internationalization_guidelines/Tutorial and requested feedback on the parent talk page. I also made additional updates to key documentation pages; see the latest task description update for edit links. I'll be wrapping up this project next week by making remaining edits to update content and finalizing cleanup tasks.

apaskulin updated the task description. (Show Details)Jun 23 2025, 4:43 PM
apaskulin closed this task as Resolved.Jun 27 2025, 6:40 PM
apaskulin updated the task description. (Show Details)
apaskulin moved this task from Active projects to Done on the Tech-Docs-Team board.

This week, I completed the remaining to-dos for this project to wrap it up, including edits to address in-scope use cases and updates to link related pages.

Waddie96 subscribed.Aug 20 2025, 10:57 PM
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits