Understanding translation administration

Hi! I’m Rae, a Movement Communications Associate at the Wikimedia Foundation, and long-time Wikimedia volunteer. I’ve put together this post to provide a conceptual introduction to using the Translate extension for new or aspiring translation administrators. The first half of this post presents concepts, and the second half provides a more practical discussion of some example applications in preparing pages for translation.

The Translate extension allows us to create and manage translatable pages. A working understanding of its process and features is integral to an effective presentation of content on multilingual wikis, used for everything from large projects like the Foundation’s Annual Plan, to CentralNotice banners, to individual pages. Becoming comfortable with this tool opens up a range of options to improve the accessibility of wiki content, allowing users from diverse linguistic backgrounds to engage together with the page’s ideas.

What does it do?

Before the Translate extension, translating a page meant a lot of manual work. No system existed to manage translations, meaning that pages and their translations were not intrinsically connected or synced. Each part of a page had to be recreated manually in every language version, and updates to the source page were manually added to all other pages. It wasn’t possible to vary only the text between languages, nor was it possible to automatically sync changes. In essence, pre-Translate extension translations were just links to a copy of a page in another language, created and updated entirely manually.

The Translate extension dramatically changed this landscape, creating a user-friendly interface for translators, and a powerful, well-documented tool for translation administrators. In short, the extension allows defined parts of a page’s content (known as translation units) to vary by language. When readers select a language, the extension swaps out the source language’s units with that of the selected language, provided those translated units exist.

Technically speaking, it’s not that simple. The extension uses a complicated series of subpages, but importantly, these are managed by the extension. For readers, translators, and (usually) translation administrators, it is that simple: changes are synced across all language versions with the click of a button, translators see only the content which needs to be translated, and readers are shown a seamless switch between languages as though it was truly the same page.

Who uses the extension?

At a high level, there are three categories of users whose interactions are coordinated by the translate extension: readers, translators, and translation administrators.

Readers interact with translatable pages through the languages bar, viewing available translations and their completeness, and selecting their preferred language.

Translators interact with translatable pages through the Special:Translate interface, providing translations for translation units.

Translation administrators add markup to define translation units (or verify markup placed by non-translation admins), mark pages for translation, and handle translatable page management.

The reader experience

Readers select their intended language through the languages bar at the top of a translatable page:

The icon to the right of each language denotes the progress of those translations. A complete circle indicates a complete translation.

Clicking a language sends the reader to a subpage of the source page.  On that subpage, translation units are shown in the selected language, if those units have been translated into that language by other editors. Where those units have not been translated, the source language units are shown. Content not in a translation unit does not change between the source and translated versions.

If a unit on the source page has been updated since its translation into a given language, and it was marked as a significant update, readers in that language will be shown the old translation with a pink highlight indicating that it is outdated.

The translator experience

The role of translators is to provide accurate translations of the source page’s translation units. Rather than translating an entire page in one big block, they translate individual units. These units are defined by the users who prepared and marked the page for translation.

Translating is done through the Special:Translate interface. Users are shown individual translation units, which they can then provide a translation for. They can either pick a specific page to translate, or view a centralized feed of units needing translation into their selected language.

Everything in a translation unit can vary between page languages. This means that formatting inside the unit needs to be appropriately copied over by the translator. In the above example, this includes a bullet point (*), bold tags (”’ ”’), and a link ([[$1| ]]). 

What’s important to note here is the “$1”. This is a translation variable, also known as a “tvar” or “insertable”. When the translation is shown to readers, the $1 will be replaced by the contents of the tvar named “1”. In this case, it is the page title that the link goes to. The use of translation variables abstracts non-translatable elements, like link targets and file names, away from the translator experience. Those do not need to change based on language, and are thus not relevant for translators. Additionally, these allow the non-translatable elements to be changed for all language versions with a single edit to the source page, without needing to update each individual translation.

As an aside, note the title of the translation unit’s page on the top left of that screenshot. It is the title of the translatable page (“Wikimedia Foundation Annual Plan/2023-2024”), in the translations namespace (“Translations:”), with “/8/ru” appended to it. This indicates that it is the Russian (“ru”) translation of unit 8 for that page.

Preparing pages for translation

When a volunteer goes to translate a page, the units they are shown are defined by Translate extension-specific markup. Effective and precise use of this markup can make a big difference in improving the translator experience, and by extension the experience of readers.

Though technically anyone can add translate markup to a page, it is the role of translation administrators to verify correct markup and indicate to the extension that the page is ready to be translated. The primary goal in preparing a page for translation is to limit, as much as possible, content in translation units to only what needs to be translated.

If you are new to translate markup, I would recommend becoming comfortable with the basics before continuing with this post. Here are a few useful resources:

• Simplified tutorial with videos
• More complete documentation, with example markup and notes
• Marking pages for translation guide that I wrote, intended to be entry-level and more linearly organized

Optimizing the translator experience

The content we want to include in translation units are that which need to vary between language versions, and as little as possible which is language-invariant.

So, what does this goal mean in practice? Let’s review a few examples and discuss how our choices impact the translator experience.

Images

<translate>[[File:Fun image|frameless|300px|This is a fun image.]]</translate>

This would allow the entire image call to vary between language versions, which is unnecessary and prone to error in translators copy/pasting (or attempting to translate) it.

As an aside: in some cases, you may want to have different files appear in different languages. However, this is rarely how you would do that. In those cases, it is best for the image name and caption to be in separate units, allowing the other-language file names to be specified on their own. Also, be sure to include message documentation for that unit so translators know not to translate the file name normally.

So, how can we fix this? An initial thought might be to wrap all of the language-invariant content in a tvar:

<translate>[[<tvar name="1">File:Fun image|frameless|300px</tvar>|This is a fun image.]]</translate>

This is better, but is not optimal. The translator is still presented with content that does not need to vary between languages and for which there is no necessity to include it, even though it is shortened with a tvar.

With images, we can simply wrap the caption itself in translate tags:

[[File:Fun image|frameless|300px|<translate>This is a fun image.</translate>]]

In this setup, the translator is presented only with the text that needs to be translated. We have optimized the translator’s experience with this translation unit.

Styling

<translate><span style="color:blue">Above, there is a fun image.</span></translate>

In this example, the span tags are included in the translation unit, and thus would need to be copied over by the translator. This is unnecessary. In general, any styling that is applied to an entire translation unit of text can be specified outside the translate tags:

<span style="color:blue"><translate>Above, there is a fun image</translate></span>

Perfect, so now the translator only sees the text that needs to be translated.

What do we do if the formatting is only applied to part of a translation unit? In some cases, we can turn it into multiple translation units and add the styling syntax outside of the translate tags. However, if it’s mid-sentence, breaking it up into multiple units would make it impossible to translate. Instead, in this case we need to use a tvar:

<translate>Above, there is a fun image. It has <<tvar name="1">span style="color:blue"</tvar>>a lot of blue<<tvar name="2">/span</tvar>> in it.</translate>

The translator is still presented with language-invariant content, however, it is shortened with tvars: all they will need to type is “<$1>” and “<$2>”. We have optimized the translator’s experience with this translation unit.

Some types of styling are short and ubiquitous enough that it is not worth using tvars for. Namely, italicized or bold text. In cases like those, it is often useful for the translator to know what the styling is, so that they can maintain the same emphasis in the translated version. (additionally, not all scripts support bold or italics)

For a similar reason, it is not a good idea to include all opening/closing syntax inside a tvar: above, the result is “<$1>”, not simply “$1”. This is so that the translator has a sense of what the tvar is, whether it’s styling “<$1>” or a link target “[[$1|” or something else. If you have longer styling (like with the span tag above) that might be relevant in translation, you can still use a tvar, though with a more descriptive name or message documentation. Other types of formatting need to be included in translation units for technical reasons, namely, section headings. As of T62544, section headers should be in their own translation unit, including the == signs. As an example:

<translate>
== Section header ==

Text.
</translate>

This allows Special:MyLanguage links to a section of a translatable page (e.g., [[Special:MyLanguage/Page#section]]) to properly link to that section in translated versions.

Tables

This is an excerpt from a table I formatted earlier this year:

{| class="wikitable" style="float:right; margin-left:10px;"
|+ <translate><!--T:29--> Remaining funds (USD)</translate>
!
! style="background: #404040; color: white" | <translate><!--T:30--> Initial</translate>
! style="background: #970302; color: white" | <translate><!--T:31--> Round One</translate>
! style="background: #0E65C0; color: white" | <translate><!--T:32--> Round Two</translate>
|-

Like in the previous examples and discussion, our goal is to present the translator with only the content that needs to change between languages. In the above example, I do this by wrapping the text content of each cell with translate tags.

The larger the table, the more copy-pasting of “<translate>” you’ll need to do. However: more work in preparing the page for translation means a better experience for translators, and in turn better translations for readers. There might be a hundred translate tags on a page if that’s what is needed to optimize the translator experience. Or, if it’s only text and headers, there might just be two.

The role of translation administrators

In the section above, I discuss a handful of markup examples to illustrate the types of choices translation administrators make in determining how to prepare a page for translation. The role of the translation administrator, however, is more than adding and verifying markup: they mark pages for translation, manage changes to the source page’s content, determine whether to mark an updated translation unit as outdated, provide message documentation, and more.

My intent with this post is to frame the role of the translation administrator as a curator of the translator experience, who in turn can provide the best possible experience for readers. This is a useful mindset to have when preparing a page for translation and in subsequent page management. If someone is going to be volunteering their time to translate content, or seeking to read a page’s content in their language, we want to ensure that their experience in doing so is as good as we can make it. We also want to listen to feedback from readers, translators, and other translation administrators, recognizing that our decisions determine the translatability of a page. Though many people’s work has to come together to create a page translated into many languages, it is the translation administrator who defines how (and how efficiently) that happens.