How to Configure and Use the Translate Extension for Multilingual Content in MediaWiki

Introduction

The Translate extension turns a single-language MediaWiki into a fully multilingual publishing platform. It provides in-wiki translation of interface messages, software strings and, most importantly, structured page translation. The extension is bundled together with a handful of supporting extensions in the MediaWiki Language Extension Bundle (MLEB), which gives you a ready-to-run configuration.

Installation Overview

While you could install Translate alone, the recommended way is to install the whole bundle. The bundle includes:

• UniversalLanguageSelector (ULS) - language chooser UI
• CleanChanges - nicer recent-change displays for translations
• LocalisationUpdate - automatic import of interface messages
• Translate - the core translation engine

Download the latest bundle from the installation page. Extract the extensions into extensions/ and follow the steps below.

Step 1 - Load the Extension

wfLoadExtension( 'Translate' );

Place the line in LocalSettings.php after the core MediaWiki configuration.

Step 2 - Grant User Rights

Translate introduces several new rights. At a minimum you need the ability to edit translations and, for page translation, the pagetranslation right.

// Allow registered users to translate messages
$wgGroupPermissions['user']['translate'] = true;
// Optional - skip CAPTCHA for translators (required if ConfirmEdit is active)
$wgGroupPermissions['user']['skipcaptcha'] = true;

// Sysops may mark pages for translation and manage groups
$wgGroupPermissions['sysop']['pagetranslation'] = true;
$wgGroupPermissions['sysop']['translate-manage'] = true;
$wgGroupPermissions['sysop']['translate-messagereview'] = true;

Fine-tune rights according to your workflow (e.g. a separate translator group).

Step 3 - Basic Configuration Variables

The most common variables are documented on the configuration page. Below are the essential ones.

# Documentation language (qqq is the default for Translate)
$wgTranslateDocumentationLanguageCode = 'qqq';

# Enable page translation feature (required for translatable pages)
$wgEnablePageTranslation = true;

# Namespace used for translated pages - keep the default unless you have a conflict
$wgPageTranslationNamespace = 1198;

# Optional: redirect users to the translation of the current page when they change UI language via ULS
$wgTranslatePageTranslationULS = true;

These settings are enough to start translating both interface messages and content pages.

Step 4 - Message Group Configuration (optional)

Translate works with message groups - collections of strings that share a source file or purpose. For most wikis the default groups (core, extensions, etc.) are sufficient, but you can add custom groups via YAML files:

$wgTranslateGroupFiles[] = "$IP/extensions/Translate/groups/MyProject/MyProject.yml";

The YAML format is documented in groups/ of the extension repository. Typical keys are source, path, type and languages.

Step 5 - Machine Translation & Translation Memories (optional)

If you want on-the-fly suggestions, configure one of the supported services (Apertium, Microsoft Translator, Yandex, or a private TTMServer). Example for Microsoft Azure:

$wgTranslateTranslationServices['Microsoft'] = [
    'url'   => 'https://api.cognitive.microsofttranslator.com/',
    'key'   => 'YOUR_AZURE_KEY',
    'type'  => 'microsoft',
    'timeout'=> 5,
];

Remember to enable curl in PHP and allow outgoing HTTPS traffic.

Step 6 - Workflow States (optional)

For larger translation projects you can enable a simple review workflow. Define colour-coded states and the rights required to set them:

$wgTranslateWorkflowStates = [
    'new' => [ 'color' => 'FF0000' ],               // red - just created
    'needs_proofreading' => [ 'color' => '0000FF' ], // blue - needs review
    'ready' => [ 'color' => 'FFFF00' ],             // yellow - reviewed
    'published' => [
        'color' => '00FF00',                       // green - live
        'right' => 'centralnotice-admin',
    ],
];

Users with translate-groupreview can change the state from Special:Translate.

Step 7 - Caching & Indexing

For wikis with many groups the message index can become a bottleneck. The default storage uses the database, but you can switch to a serialized index or CDB if you have a dedicated cache directory:

$wgTranslateCacheDirectory = "$IP/cache/translate";
$wgTranslateMessageIndex = [ 'DatabaseMessageIndex' ]; // or 'SerializedMessageIndex'

After changing the index type run the maintenance script to rebuild it:

php extensions/Translate/scripts/createMessageIndex.php

Step 8 - Sandbox for New Translators (optional)

If you want a low-friction onboarding experience, enable the sandbox:

$wgTranslateUseSandbox = true;
$wgTranslateSandboxPromotedGroup = 'translator'; // promote after review
$wgTranslateSandboxLimit = 20; // max translations per sandbox user

Sandbox users can translate but their edits are not visible to the public until promotion.

Using the Extension

Marking a Page for Translation

There are two approaches:

• Page translation - add the magic word <translate> to the page source. Example:

<translate>
This is the English source.
{{int:welcome-message}}
</translate>

When the page is saved, a translation page will be automatically created in the Translations namespace (e.g. PageName/zh for Chinese). The interface shows a language selector on the left sidebar (or via Special:MyLanguage links).

• Message groups - for interface strings, edit the corresponding MediaWiki:* or extension messages using Special:Translate. The editor provides a side-by-side view of source and target, fuzzy markers and a comment field.

Translating via Special:Translate

Navigate to Special:Translate. The page lists all groups, their completion percentages and a filter for language. Click a group, then the "Untranslated" task to see a queue of strings. The editor offers:

• Source text (read-only)
• Target textarea with optional syntax highlighting
• Buttons for "Fuzzy", "Mark as reviewed", "Save & next"
• Links to the documentation language (qqq) for context

When you save, the translation becomes visible on the translated page instantly. If $wgTranslateKeepOutdatedTranslations is true, outdated parts stay marked with !!FUZZY!! until a reviewer clears them.

Review & Proofreading

Users with the translate-messagereview right can mark translations as reviewed. The review status is shown as a coloured badge (green when published). Proofreaders can also add comments that appear in the history.

Language Selector Integration

ULS adds a dropdown on the top-right of every page. With $wgTranslatePageTranslationULS = true a user who switches the UI language is automatically redirected to the corresponding translation (if it exists). For static links you can use the Special:MyLanguage syntax, e.g.:

[[Special:MyLanguage/Help:Getting_started|Getting started]]

This makes the link always point to the page in the user’s current UI language.

Troubleshooting Common Issues

• "tpt-unknown-page" error on save - the page has been marked for translation but the background job queue has not processed the creation of the translation page. Run the job queue manually or set up a cron job as described in Manual:Job queue.
• Translations not appearing - check that $wgEnablePageTranslation is true and that the page is in a content model allowed for translation (default is text/x-wiki). Use Special:PageTranslation to verify the page’s status.
• Machine-translation suggestions missing - verify the service key, ensure curl is enabled and that outbound HTTPS is not blocked by a firewall.

Unbalanced <translate> tags - ensure every opening tag has a closing tag and the page size is below the PHP PCRE limit. Increase the limit in LocalSettings.php if necessary:

ini_set('pcre.backtrack_limit', 400000);

Best Practices for a Healthy Multilingual Wiki

1. Use a dedicated translator group - assign translate and translate-messagereview rights, keep the group small to avoid edit wars.
2. Document source strings - fill the qqq documentation language. Translators can see usage notes, parameters and context.
3. Keep page source stable - avoid frequent structural changes to translatable pages; otherwise translators must re-translate large sections.
4. Leverage translation memories - enable a TTMServer or a local SQLite memory to reduce duplicate work.

Periodically run maintenance - rebuild the message index and refresh caches after bulk imports:

php extensions/Translate/scripts/createMessageIndex.php
php maintenance/rebuildRecentChanges.php

Conclusion

With a few lines in LocalSettings.php, appropriate user rights and optional tweaks for workflow, caching and machine translation, the Translate extension provides a robust multilingual solution for any MediaWiki installation. Whether you run a small community wiki or a large documentation portal, the same core steps—load the extension, enable page translation, grant rights, and configure optional services—will get you up and running. The integrated UI (Special:Translate, language selector, fuzzy markers) makes it easy for contributors to add, review and maintain translations, while the powerful backend (message groups, YAML configuration, workflow states) gives administrators fine-grained control over the translation pipeline.

For the latest details, always refer to the official Help:Extension:Translate pages and the Configuration guide. Happy translating!