By MW in mediawiki — 15 Sep 2024

Configuring Multi Language Support in MediaWiki with the Translate Extension

```html

Why multilingual matters in a wiki world

Picture this: you’re browsing a community‑driven knowledge base, but the article you need lives in a language you barely skim. Frustrating, right? That’s the exact gap the Translate extension was built to bridge. Not just a fancy add‑on, it’s the glue that lets contributors speak their native tongue while still feeding a single, coherent repository.

Sure, you could spin up separate wikis for each language – that’s what some folks do, but then you end up with a maintenance nightmare. Imagine juggling ten different DBs, ten different skins, ten sets of extensions. My brain hurts just thinking about it. With Translate, you keep one codebase, one set of users, and still serve, say, English, Swahili, and Japanese side‑by‑side.

First steps: grabbing the extension

Alright, let’s roll up our sleeves. The extension lives on git – you can pull it straight into extensions/Translate or use Composer if you fancy that route. I’ll stick to the classic git way because it’s the most transparent for newbies.


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

Don’t forget to run composer install inside the new folder if you haven’t already set up Composer for MediaWiki. A tiny hiccup: the first time you run it, Composer may whine about missing php extensions – just install intl and you’re golden.

Turning the switch on

Now open LocalSettings.php. Add the line that tells MediaWiki “hey, this thing exists”. It’s as simple as a whisper to a friend.


wfLoadExtension( 'Translate' );

Optionally, you can set a few defaults right away. I usually dump these in right after the load line because they’re easy to forget later.


$wgTranslateUseSandbox = true;               // sandbox for translators
$wgTranslateTranslationServices = [          // pick your machine translation provider
    'GoogleTranslate',
];

Save the file. Then clear the cache – either via php maintenance/update.php or just bust the browser cache if you’re in a dev environment.

Defining the languages you want to support

Here’s where the rubber meets the road. MediaWiki already knows a few language codes (en, de, fr…), but you might need to add “tlh” for Klingon (just kidding… unless you’re running a Star Trek fan wiki).

Open LocalSettings.php again and sprinkle in a language list. The order matters – the first entry becomes the default UI language for anonymous users.


$wgLanguageCode = 'en'; // core UI language
$wgTranslateSupportedLanguages = [ 'en', 'es', 'fr', 'de', 'pt' ];

Note: you can also let users pick any language that MediaWiki knows about, but limiting the list keeps the UI tidy. Trust me on that; I once left the full list on a small site and the language selector turned into a gigantic dropdown that looked like a bad pizza menu.

Setting up language groups

Translate lets you bundle languages into “groups” – handy when you want the same message to be shared across variants. For example, “pt‑BR” and “pt‑PT” both belong to the “pt” group.

Add this snippet somewhere after the previous settings:


$wgTranslateLanguageGroups = [
    'pt' => [ 'pt', 'pt-br', 'pt-pt' ],
    'zh' => [ 'zh-hans', 'zh-hant', 'zh-cn', 'zh-tw' ],
];

Now, when a translator works on the “pt” group, they’re essentially handling both Brazilian and European Portuguese. Saves effort, avoids duplicate work. It’s like cooking one sauce for two dishes – why make two separate pots?

Creating translatable pages

Okay, you’ve got the extension loaded, languages declared, and groups set. Time to actually mark some wiki pages for translation. The key is the {{int:}} magic word, but you’ll mostly be working with the Special:Translate interface.

Navigate to Special:Translate and click “Add a new message group”. You’ll see a wizard that asks for a group ID, a label, and a source language. The source is usually English, unless your community’s primary language is something else.

My favorite tip: name the group ID after the namespace it belongs to. For instance, if you’re translating all pages in the “Help” namespace, call it help. It keeps the backend tidy and the UI intuitive.


// Example of a simple message group definition in a JSON file
{
    "@metadata": {
        "authors": [ "YourName" ]
    },
    "group": "help",
    "label": "Help pages",
    "sourceLanguage": "en",
    "languages": [ "en", "es", "fr", "de", "pt" ]
}

Drop that JSON into extensions/Translate/messageGroups/ (or wherever your site’s custom groups reside). Then run php maintenance/rebuildmessages.php to make MediaWiki aware of the new group.

Translating a page – a quick walkthrough

Find the page you want to translate, e.g., Help:Editing.
Click the “Translate” tab that now appears next to “Edit”.
Select the target language from the dropdown – say “es” for Spanish.
The interface shows the original wikitext on the left, a blank field on the right.
Copy‑paste any variables (like {{{{PAGENAME}}}}) exactly; don’t tamper with them.
When you’re done, hit “Save translation”. It lives alongside the source, not overwriting it.

Quick note: the translator sees a “preview” button that renders the target wikitext just like a regular page. It’s a lifesaver because you can spot broken links or missing templates before they go live.

Handling plural forms and gender

Languages love to be quirky. English has the simple “one vs. many” rule; Russian has three forms; Arabic has six. Translate’s {{PLURAL}} and {{GENDER}} magic words make this manageable.

Example for English/Spanish plural handling:


{{PLURAL:$1|There is $1 item|There are $1 items}}

In Spanish you’d write:


{{PLURAL:$1|Hay $1 elemento|Hay $1 elementos}}

Don’t forget the colon after the variable name – it’s a tiny detail that trips up new translators. I once missed it and the page threw a baffling “Message key not found” error. Oops.

Automating translations (optional)

If your wiki is huge and you need a head start, you can plug in Google Translate or Microsoft Translator. The config we added earlier ($wgTranslateTranslationServices) tells the system which engines to call.

Beware: machine translations are good for a “first draft”, not final copy. They often stumble on idioms. I once got “the cat is on the roof” turned into “the cat sits atop the ceiling” – technically correct, but sounds stilted.

To enable auto‑suggestions, go to Special:Translate/GroupConfiguration, find your group, and tick “Enable machine translation”. Then translators will see a “Copy from machine” button on each field.

Common pitfalls and how to dodge them

Forgot to run update scripts. After any change to LocalSettings.php or message groups, run php maintenance/update.php. Skipping this step leaves the UI in a limbo state where the “Translate” tab might disappear.
Namespace mismatches. If you declare a group for “Help” but actually store messages in “Documentation”, Translate won’t find them. Double‑check the group ID matches the actual namespace.
Missing intl extension. Without PHP’s intl, plural handling breaks for many languages. Install php-intl via your OS package manager (e.g., apt-get install php-intl).
Over‑restricting language list. If you later decide to add “nl” (Dutch) but didn’t include it in $wgTranslateSupportedLanguages, users will see a “language not available” error. Keep the list flexible or remember to edit it later.
Hard‑coded English strings. Some wikis sprinkle plain English inside templates, bypassing {{int:}}. Those won’t be translatable. Run a grep for common English words in your templates and replace them with message keys.

Testing your setup – a sanity checklist

Log out, visit the wiki as an anonymous user. Does the language selector appear?
Pick a non‑default language, navigate to a translated page. Does the UI (menus, tooltips) switch accordingly?
Open a translated page in “view source” mode. Do you see the original wikitext on the left and the translated version on the right?
Try editing a translation. Does the preview render correctly, with all templates intact?
Finally, check the “Special:TranslationStats” page. It should list the groups you created and show progress percentages.

If any of those steps feel off, retrace your steps – usually a missing semicolon in LocalSettings.php or a typo in the language code is the culprit.

Final thoughts

Adding multilingual support with Translate isn’t a “set‑and‑forget” operation; it’s more like tending a garden. You plant the extension, water the configuration, prune broken links, and watch the community blossom across languages. The payoff? A richer, more inclusive knowledge base where contributors from Nairobi to Kyoto feel right at home.

And hey, if you ever find yourself staring at a wall of {{PLURAL}} statements and wonder why Russian has four plural forms, remember: language is messy, but that’s what makes it beautiful. Embrace the chaos, keep the docs handy, and let your translators do what they do best – turn tech‑talk into something anyone can understand.

```