Configuring MediaWiki for Multilingual Support with Translate Extension

Why Multilingual MediaWiki Matters

Imagine a community wiki that only speaks English while half of its contributors type in Spanish, Japanese, or Swahili. The knowledge stays locked behind a language wall, and the project stalls. MediaWiki, the engine behind Wikipedia, can break that barrier—if you empower it with the Translate extension. The result? A single wiki, many tongues, and a smoother translation workflow that feels native to editors.

Getting the Basics Right

Before you dive into the nitty‑gritty, make sure your MediaWiki core is recent enough. The Translate extension officially supports MediaWiki 1.35+; anything older will throw odd errors that no amount of debugging can fix. Once that's sorted, grab the extension from the repository:

cd /path/to/mediawiki/extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Translate.git

Pop the Translate directory into extensions/, then pop open LocalSettings.php and add a single line:

wfLoadExtension( 'Translate' );

If you’re nervous about breaking an existing wiki, add the line at the very end of the file—right before the ?> (or leave off the closing PHP tag entirely; modern MediaWiki doesn’t need it). Save, clear the cache (php maintenance/eval.php "wfResetAllCaches();"), and you should see a new “Special:Translate” link in the toolbox.

Core Configuration Settings

Out of the box, Translate does not know which languages you intend to support. That’s where a handful of $wg variables come in. Place them anywhere after the wfLoadExtension call.

// Languages you want to enable – use ISO‑639‑1 codes
$wgTranslateLanguageFallbacks = [
    'en' => [ 'de', 'fr' ], // English pages will fall back to German then French
];

// Default language for the UI if a user has no preference
$wgDefaultUserOptions['translate-language'] = 'en';

// Permission groups – who can translate, review, and manage translations
$wgGroupPermissions['user']['translate']          = true;   // basic translation rights
$wgGroupPermissions['translator']['translate-messagereview'] = true;
$wgGroupPermissions['manager']['translate-groupreview'] = true;

Notice the array syntax—no extra trailing commas, otherwise PHP will choke on older versions. Also, the fallback list can be as long as you like, but keep it sensible; too many layers slow down page rendering.

Setting Up Content Translation

Most wikis start with interface translation (the MediaWiki: namespace) and then move to full‑page translation. To enable the latter, turn on the “Content Translation” feature:

$wgTranslatePageTranslation = true;

That single toggle adds the “Translate” tab on every content page. Clicking it opens the translation wizard, which walks the editor through source extraction, machine‑assisted suggestions, and finally a review step. The wizard respects the language list you defined earlier.

Creating Language‑Specific Namespaces

By default, Translate stores translations in the same namespace as the source page, using a suffix. For example, Help:Editing in English becomes Help:Editing/de for German. If you prefer a cleaner URL scheme, you can map language codes to separate namespaces via $wgNamespaceAliases:

$wgNamespaceAliases['Help_de'] = NS_HELP . 1; // second Help namespace for German

Now German help articles sit under Help_de:Editing. This approach is optional but handy for large multilingual wikis where the suffix method becomes unwieldy.

Interface Message Translation

Translating the UI is a different beast. MediaWiki stores messages in the MediaWiki: namespace (e.g., MediaWiki:Cancel). When Translate is active, those pages become editable just like any other content. The trick is to make sure the page exists for each language you support. A quick way is to enable AutomaticMessageGroupCreation:

$wgTranslateAutomaticMessageGroupCreation = true;

This tells the system to generate a message group for every language automatically, and you’ll see them appear under “Special:TranslationStats”. From there, assign a translator (or set the group to “allowed”), and let the community polish the text.

Handling Variants and Plurals

Languages like Chinese have simplified/traditional variants, while Slavic tongues have complex plural rules. Translate leverages the CLDR extension for this. Install it alongside Translate:

git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CLDR.git

Then load it:

wfLoadExtension( 'CLDR' );

After that, you can define variant fallbacks:

$wgTranslateVariantFallbacks = [
    'zh-hans' => [ 'zh-hant' ], // Simplified Chinese falls back to Traditional
    'pt-br'   => [ 'pt-pt' ],   // Brazilian Portuguese falls back to European Portuguese
];

These fallbacks are consulted when a specific variant isn’t available, preventing “missing message” warnings on the UI.

Workflow: From Draft to Published Translation

Let’s walk through a typical translation cycle. Suppose a user named Ana clicks “Translate” on the page Project:Roadmap. The wizard shows the source text, a machine‑translation suggestion (if you enabled $wgTranslateEnableMachineTranslation), and a “Submit” button. Ana fills in the German version, then clicks “Submit”. The page lands in the “review” queue, visible to members with the translate-messagereview right.

Reviewers (maybe “Bob” from your translator group) open “Special:TranslationReview/de”, compare the source and target, and either accept or reject. Accepted translations become live instantly; rejected ones stay in the draft area, marked with a red banner. The system also logs every action in Special:Log/translate, providing full auditability.

That’s the gist, but there are two hidden details most people overlook:

• Translation memory. Translate caches previous translations, offering them as suggestions for similar strings. It’s a subtle time‑saver that can dramatically boost consistency across pages.
• Glossary support. By adding gloss entries in Special:Translate/Glossary, you can enforce terminology—crucial for technical wikis where “node” vs. “vertex” matters.

Troubleshooting Common Pitfalls

Even after following the steps above, you might hit a snag. Here are the usual suspects:

1. Missing language tab. Double‑check that $wgTranslatePageTranslation is true and that the page is not protected from editing.
2. Permission errors. If translators see “You don’t have permission to translate this page,” verify group rights in LocalSettings.php and run php maintenance/update.php after any permission changes.
3. Broken fallback. When an interface message shows “[[MediaWiki:Foo/en]]” instead of the actual text, the fallback chain is broken. Inspect $wgTranslateLanguageFallbacks for typos.
4. Cache storms. Translate heavily relies on the object cache. For high‑traffic wikis, configure $wgObjectCaches to use Memcached or Redis; otherwise you’ll see stale translations for minutes.

Best Practices for a Healthy Multilingual Wiki

There’s no silver bullet, but a few habits pay off:

• Start small. Pick a core set of languages (e.g., en, de, fr) and expand as the community shows demand. Too many languages early on cause navigation chaos.
• Document your workflow. Write a short “Translation Guide” page in each language, linking to Special:Translate pages, so newcomers know where to start.
• Use language‑specific categories. Create Category:German translations (or its localized name) to collect translated pages. It helps reviewers locate missing content.
• Keep your extensions up to date. Translate and CLDR receive regular security patches. Set up an automated cron job to pull the latest releases.

Putting It All Together

To recap, the path to a truly multilingual MediaWiki looks roughly like this:

// 1. Install core
wfLoadExtension( 'Translate' );
wfLoadExtension( 'CLDR' );

// 2. Define languages and fallbacks
$wgTranslateLanguages = [ 'en', 'de', 'fr', 'es', 'zh-hans', 'zh-hant' ];
$wgTranslateLanguageFallbacks = [
    'en' => [ 'de', 'fr' ],
    'zh-hans' => [ 'zh-hant' ],
];

// 3. Enable page translation and set defaults
$wgTranslatePageTranslation = true;
$wgDefaultUserOptions['translate-language'] = 'en';

// 4. Permissions
$wgGroupPermissions['user']['translate'] = true;
$wgGroupPermissions['translator']['translate-messagereview'] = true;
$wgGroupPermissions['manager']['translate-groupreview'] = true;

// 5. Variant handling (optional)
$wgTranslateVariantFallbacks = [
    'pt-br' => [ 'pt-pt' ],
];

// 6. Misc settings
$wgTranslateAutomaticMessageGroupCreation = true;
$wgTranslateEnableMachineTranslation = true; // if you have a MT service configured

Paste that into LocalSettings.php, run php maintenance/update.php, clear the cache, and you’re set. From there, treat the wiki like any other collaborative project: invite speakers, let them claim pages, and watch the content blossom in multiple tongues.

Final Thoughts

Multilingual support isn’t just a fancy add‑on; it’s a strategic move that can dramatically broaden your audience. The Translate extension gives you a robust, battle‑tested toolkit—one that powers Wikipedia itself. With a bit of configuration, a sprinkle of community spirit, and the occasional debug session, your MediaWiki can become a truly global knowledge hub.