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 file, 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:

The four translate helpers come with both products. The commands on this page are the Docker form; the standalone binary runs the same four against its working directory, as wikven translate mark --all and so on, with no mount to arrange. See Commands.

$ 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:

$ 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.

Those markers are also what makes the file a translation rather than a subpage. Hundreds of language codes are ordinary English words too — id, no, is, it, as, be — so API/id under a translatable API is far more often a page about identifiers than an Indonesian translation. Wikven reads it as a translation only when it carries the source's  markers, and builds it as a page of its own otherwise. Write a translation with translate scaffold and this never comes up; write one by hand and translate check will tell you the file was read as a page.

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. Only those markers and their text belong in the file: the <translate> tags, and whatever the source page keeps outside them, stay on the source page, where the export reads them for every language. One written here is swallowed by the unit above it, and that unit is then shown in the source language rather than yours — so translate check refuses it.

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

When you have translated a page, run translate stamp on the translation you wrote, so its units record the source version you wrote them against. Mount your source directory writable:

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

One translation at a time, and there is no flag for the whole tree. A stamp is not something the tool can work out: it is your word that you read the unit against the source it now claims to match. Stamping a page you did not open would say that about translations nobody has looked at, and a translation left behind would then read as current -- which is exactly what the stamp exists to catch.

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:

$ 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. Set its comment input and it also leaves one comment on the pull request, grouping what it found and naming the command that answers each group — written for a contributor sending their first translation, who has the annotations but not the workflow behind them. Add comment-languages: auto and the comment is written in English and in the language of any translation the pull request touches, from wikven's own interface messages; a change to an English page alone is answered in English alone. 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.

← JavaScript

Editing sidebar →