Translating

Wikven can build a site in more than one language using MediaWiki's Translate extension. Translate normally expects translators to work in an in-wiki editor, which a static build has no room for, so Wikven drives it from your source tree instead: you translate by adding files and committing them, the same way you write any other page.

Enabling translation

Add Translate to extensions in your .wikven.yaml, along with UniversalLanguageSelector, which Translate depends on. Both are bundled in the Wikven image, so there is nothing to install.

extensions:
  - UniversalLanguageSelector
  - Translate

A static export cannot serve UniversalLanguageSelector's runtime webfonts (they load from a live endpoint), so by default Wikven turns them off and readers see each script in their own system fonts. Set WikvenBundleWebfonts to bake the fonts into the site instead, so a reader whose system lacks a font for a script still sees the intended typeface.

You do not list the languages you translate into: as with Translate itself, a language exists as soon as a translation for it does. The language you write your pages in stays the source language.

Marking a page for translation

Wrap the parts of a page that should be translated in <translate> tags, add <languages/> where you want the language bar, and give each unit a  marker. This is Translate's own page-translation markup:

<languages/>
<translate>
<!--T:1-->
{{SITENAME}} builds static sites from MediaWiki.

<!--T:2-->
It runs a real MediaWiki at build time.
</translate>

You do not number the units by hand. Wrap the content in <translate> and add <languages/>, then run translate mark to insert the  markers, mounting your source directory writable:

$ wikven translate mark --all

$ docker run --rm -v "$PWD/src:/workspace/src" ghcr.io/chaotic-ground/wikven translate mark --all

Pass a single file instead of --all to mark just that page. Marking is idempotent and stable: it keeps the numbers already there and only adds markers for new units, so re-run it whenever you add content. The numbers are the unit identity; a translation references them to line its units up with the source. The build renders the language bar and, for each language, a page at Page/lang.

Adding a translation

A translation lives next to the page, named <Page>/<lang>.wikitext: the Korean translation of Intro.wikitext is Intro/ko.wikitext. Generate its skeleton with translate scaffold, which writes an empty  marker for every source unit and lists each unit's source text as a guide:

$ wikven translate scaffold ko Intro.wikitext

$ docker run --rm -v "$PWD/src:/workspace/src" ghcr.io/chaotic-ground/wikven translate scaffold ko Intro.wikitext

Pass --all in place of a file to scaffold every translatable page. Re-running is safe: it keeps what you have translated and only appends markers for new units.

Then fill each unit's translation under its marker:

<!--T:1-->
위크벤은 미디어위키로 정적 사이트를 만듭니다.

<!--T:2-->
빌드 시 실제 미디어위키를 실행합니다.

A unit left empty counts as not yet translated: translate check reports it and the build renders it in the source language, so you can translate a page a few units at a time. The @a1b2c3d4 stamp is added by translate stamp (see below), not by hand.

Translating the page title

A page's title is a unit too, under the reserved marker . It is the one unit that is not part of the page's wikitext: its source text is the page's own title, so nothing is added to the source page and pages in the source language render exactly as they did. This is Translate's own page display title; Wikven only spells the marker shorter.

Write the translated title at the top of the translation file, ahead of the numbered units, where translate scaffold puts its marker:

<!--T:title-->
소개

<!--T:1-->
위크벤은 미디어위키로 정적 사이트를 만듭니다.

The translated page then shows that title in its heading and in the browser tab, in place of the Page/lang subpage name. Nothing else changes: translate check reports a missing or out-of-date title like any other unit, translate stamp stamps it, and renaming the source page puts every translated title out of date, exactly as editing a paragraph does.

A page that sets its own title with the DISPLAYTITLE magic word is the exception. That magic word sits outside <translate>, so it is copied into every translation of the page and fixes the same title in every language; such a page has no title unit to translate.

Stamping

After translating, run translate stamp so every up-to-date unit records the source version it matches. Mount your source directory writable:

$ wikven translate stamp --all

$ docker run --rm -v "$PWD/src:/workspace/src" ghcr.io/chaotic-ground/wikven translate stamp --all

Pass a single file instead of --all to stamp just that translation.

Keeping translations up to date

When you change a source unit, its translations no longer match their stamp and are out of date. Wikven does not hide this:

In the built site, an out-of-date unit is marked as an outdated translation, exactly as it would be on a wiki running Translate.
translate check reports every out-of-date or missing translation as a warning, and every broken source page as an error. With --gate it exits non-zero on the errors alone, so continuous integration fails on a page nobody can translate but not on a translation that is merely behind:

$ wikven translate check --gate
::warning file=src/Intro/ko.wikitext::Stale translation unit T:2 (ko)

1 translation(s) out of date or missing.

$ docker run --rm -v "$PWD/src:/workspace/src" ghcr.io/chaotic-ground/wikven translate check --gate
::warning file=src/Intro/ko.wikitext::Stale translation unit T:2 (ko)

1 translation(s) out of date or missing.

The check-translations action runs the same check on pull requests, reporting each one as an annotation on the file it belongs to. It fails the build on a broken source page and never on a translation that is behind; pass gate: false to report even a broken page without failing. This documentation site is checked this way. To bring a translation back up to date, edit it to match the new source, then translate stamp it again.

← Searching

Deploying →