Internationalisierung

Diese Website gibt es auf Englisch, Deutsch, Französisch und Spanisch. Wähle eine Sprache in der Kopfzeile oder im mobilen Menü. Beim Sprachwechsel behält Ardo Seite, Query-String und Sprungmarke bei.

Statische Sprachrouten

Konfiguriere die Sprachen in ardo.config.ts oder im Vite-Plugin ardo():

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Docs",
  i18n: {
    defaultLocale: "en",
    locales: [
      { id: "en", label: "English" },
      { id: "de", label: "Deutsch" },
      { id: "fr", label: "Français" },
      { id: "es", label: "Español" },
    ],
  },
})

Lege entsprechende Routen unter app/routes/en/, app/routes/de/, app/routes/fr/ und app/routes/es/ an. Halte die Routen-Slugs in allen Sprachen gleich. Ardo verlangt einen vollständigen Routenbaum und meldet fehlende Seiten beim Build. Es ersetzt Inhalte nicht stillschweigend durch eine andere Sprache.

Die V6-Veröffentlichung nutzt /v6/en/, /v6/de/, /v6/fr/ und /v6/es/. Ältere Dokumentationsversionen behalten ihre ursprüngliche Sprache und ihre URLs.

Oberfläche, Suche und Metadaten

Nutze useArdoLocale() aus ardo/runtime für die aktive Sprache, auch beim serverseitigen Rendern. Übergib übersetzte Texte über <ArdoRoot labels={...}> für Navigation, Suche, Hinweise, Kopierfunktionen und Seitenaktionen. Ardo formatiert das Aktualisierungsdatum in der Sprache der Route.

Die Suche lädt nur den Index der aktiven Sprache, sobald Leser das Suchfeld fokussieren oder eine Anfrage eingeben. Das generierte HTML enthält das richtige lang, die kanonische URL und Links zu den anderen Sprachfassungen. Codebezeichner und Importpfade bleiben unverändert. Die API-Referenz entsteht aus englischen Quellkommentaren; darauf weist die übersetzte Oberfläche ausdrücklich hin.

Eine MDX-Quelle mit Palamedes

Palamedes kompiliert dieses Beispiel aus einer einzigen englischen MDX-Datei. Absätze und Rich-Text-Platzhalter stammen aus den Sprachkatalogen; die React-Komponente bleibt erhalten:

Willkommen bei Ardo. Dieser Absatz wird mit Palamedes aus einer einzigen MDX-Quelle übersetzt.

Palamedes’ nativer Compiler extrahiert semantische Nachrichten aus jedem englischen Guide in docs/app/content/guide/. Beim Build wendet die Website die PO-Übersetzungen an und erzeugt die vier Sprachbäume, bevor Ardo Metadaten, Suche und Markdown-Exporte erstellt.

Gepflegt werden nur die englische MDX-Quelle und die PO-Kataloge. Git ignoriert die erzeugten Routen unter docs/app/routes/<locale>/guide/. Code, Imports, interaktive Komponenten und englische Überschriften-IDs bleiben Teil der Struktur; übersetzt werden Fließtext, Beschriftungen und Frontmatter.

Kontext für serverseitiges Rendern

Eine Website kann withRenderContext aus app/server.ts exportieren, um einen Kontext für das vollständige Rendern einer Seite bereitzustellen. Dieses Modul landet nur im Server-Bundle. Metadatenauflösung und wartende React-Komponenten laufen im selben Kontext:

import type { ArdoServerRenderContext } from "ardo/runtime"
import { createServerI18nScope } from "@palamedes/runtime/server"

const scope = createServerI18nScope()

export async function withRenderContext({ path, render }: ArdoServerRenderContext) {
  const i18n = await loadI18n(path.split("/")[1] ?? "en")
  return scope.run(i18n, render)
}

Hier ist loadI18n der Kataloglader der Website. Verwende eine unveränderliche Instanz pro Sprache oder eine neue Instanz pro Anfrage. Aktiviere keine veränderliche Sprache für den gesamten Prozess: Parallele Render-Vorgänge würden Sprachen vermischen. Im Browser initialisiert Palamedes v2 seine Laufzeit über generierte Katalogabhängigkeiten. Der Server-Hook der Website nutzt createViteCatalogDelivery() aus @palamedes/vite-plugin/delivery, um die Import Map der aktiven Sprache einzufügen und Fehler beim Laden der Kataloge vor der Hydrierung abzufangen.

Übersetzungen pflegen

Im Wurzelverzeichnis des Repositorys:

pnpm --filter ardo-docs i18n:extract
pnpm --filter ardo-docs i18n:check

Die Extraktion aktualisiert Quellnachrichten und erhält vorhandene Übersetzungen. Bearbeite die Guide-Kataloge in docs/app/i18n/guides/; gemeinsame Oberfläche und interaktives Beispiel verwenden docs/app/i18n/. Das Audit prüft fehlende Übersetzungen, ICU-Syntax und Rich-Text-Platzhalter. Das Vite-Plugin erzeugt Routen nach Änderungen an Quelle oder PO-Dateien neu. Baue die Website und führe die Browsertests zum Sprachwechsel aus, bevor du Änderungen einreichst.