Lokalisierung

Die Zeichenketten des Themes selbst — Navigationsbeschriftungen, Suche, das Versionsbanner, der 404 — werden übersetzt ausgeliefert in en-GB, en-US, de-DE, es-ES, fr-FR, pt-PT und pt-BR. Eine Seite wählt mit locales aus, welche davon sie bedient, und i18n.defaultLocale entscheidet, welche ohne URL-Präfix ausgeliefert wird.

locales wird zur Build-Zeit gelesen: Locales entscheiden über Routen und hreflang, nicht nur darüber, was eine Komponente zeichnet — die Liste zu ändern erfordert also einen erneuten Build.

#Jede konfigurierte Zeichenkette hat drei Formen

Alles, was du in die Konfiguration schreibst — eine Beschriftung, ein Titel, eine Beschreibung — darf ein Literal, ein i18n-Schlüssel oder ein Datensatz mit einer Zeichenkette je Locale sein:

label: 'Repository'                                    // Literal
label: 'app.nav.repository'                            // eigener Schlüssel
label: { 'en-GB': 'Repository', 'de-DE': 'Repository' } // je Locale

Welche es ist, entscheidet sich daran, ob die Zeichenkette ein registrierter Schlüssel ist. Eine einsprachige Seite begegnet den anderen beiden Formen also nie, und eine Seite mit einer Handvoll Zeichenketten in fünf Sprachen braucht überhaupt keine Locale-Dateien — die Datensatzform löst über die Basissprache auf, pt-PT deckt also pt-BR ab und en-GB deckt en-US ab.

#Greife nicht in die Schlüssel der Ebene

duxt.defaults.* übersetzt die Standardwerte, die die Ebene selbst ausliefert. Diese Schlüssel sind intern: einen davon umzubenennen ist keine brechende Änderung der Ebene, und i18n beantwortet einen fehlenden Schlüssel damit, den Schlüssel auszugeben — wer sich auf einen verlässt, erführe es also von einem Leser und nicht von einem Build. Nimm ein Literal, einen eigenen Schlüssel oder die Datensatzform.

#Pfade und Links

Nur Pfade werden lokalisiert. useDuxtPath() liefert den Pfad, unter dem die Dokumentation liegt, ohne Locale-Segment; useDuxtLink() schreibt ihn als Link wieder aus und fügt das Segment erneut hinzu. Eine absolute URL, ein Mail-Link oder ein bloßer Anker geht unberührt hindurch. Alles, was einen Dokumentationspfad berechnet, sollte über dieses Paar gehen, statt die Route direkt zu lesen.

#Übersetzte Seiten

Die Oberfläche und die Seiten sind zwei getrennte Entscheidungen. Eine Seite, die nichts sagt, liefert einen Baum in jeder Locale aus — die Umgebung wechselt die Sprache, das Markdown nicht — und das ist für die meiste Dokumentation die richtige Form.

locales an einer Quelle fügt die zweite Hälfte hinzu:

sources: [{ path: 'docs', locales: ['en-GB', 'de'] }]

Die Standard-Locale ist der Baum in path selbst, ohne eigenen Ordner — dieser Schlüssel verschiebt also nie eine bereits veröffentlichte Seite. Jede andere Sprache ist ein Ordner darin — docs/de/ — oder liegt ganz woanders; siehe Mehrere Sprachen.

#Wenn eine Seite keine Übersetzung hat

Der Leser bekommt die nächstliegende Sprache, die sie hat, mit einem Banner, der das sagt, und die Seite bleibt unter noindex aus dem Index, mit einem canonical, das auf die Sprache zeigt, die den Text wirklich trägt. Die Kette ist dieselbe, die die Ebene schon auf Zeichenketten anwendet:

1. die Locale selbst — de-DE liest de-DE
2. ihre Basissprache — de-DE liest einen de-Baum, sodass ein pt/-Ordner sowohl pt-PT als auch pt-BR bedienen kann
3. ein Geschwister derselben Sprache — pt-BR liest pt-PT, bevor es aus dem Portugiesischen herausfällt
4. fallbackLocale aus vue-i18n, derselbe Wert, über den eine fehlende Zeichenkette auflöst
5. das unübersetzte Original

Ein 404 ist bewusst nicht dabei: Eine Lücke in einer Übersetzung gehört dem, der sie geschrieben hat, und sie mit dem Verstecken der Seite zu beantworten bestraft den Leser dafür.