Zum Inhalt springen
EpoCanvas Docs
EpoCanvas globale Suche
↑↓ Navigieren ↵ Auswählen ESC Schließen
EpoCanvas globale Suche

Mehrsprachigkeit & Sprachwechsel

Zuletzt aktualisiert: 22.09.2026 / Offizielle EpoCanvas Architekturspezifikation

EpoCanvas Docs verfügt über eine vollständige Mehrsprachigkeit auf Inhaltsebene: Sowohl die Oberflächentexte wie Navigation, Seitenleiste und Suchhinweise als auch der Haupttext jedes einzelnen Dokuments liegen in 10 unabhängigen Sprachversionen vor. Wenn Sie oben rechts auf der Seite eine Sprache auswählen, gelangen Sie zur Version desselben Artikels in der Zielsprache – Haupttext und Oberfläche wechseln gemeinsam.

Liste der unterstützten Sprachen

Die Website bietet derzeit 10 Sprachen, wobei Chinesisch (vereinfacht) die Standardsprache ist:

SpracheSprachnameURL-PräfixKürzel in der Oberfläche
简体中文Vereinfachtes Chinesisch (Standard)kein PräfixZH
繁體中文Traditionelles Chinesisch/zh-tw/TW
EnglishEnglisch/en/EN
日本語Japanisch/ja/JA
한국어Koreanisch/ko/KO
EspañolSpanisch/es/ES
FrançaisFranzösisch/fr/FR
DeutschDeutsch/de/DE
РусскийRussisch/ru/RU
PortuguêsPortugiesisch/pt/PT

Das Sprachverzeichnis ist in SUPPORTED_LANGUAGES in src/utils/i18n.ts definiert, die Sprachrouten sind in der locales-Konfiguration in astro.config.mjs registriert; beide Stellen müssen konsistent gehalten werden.

Sprache wechseln

  1. Suchen Sie rechts in der Navigationsleiste oben auf der Seite den Sprach-Button (er zeigt das Kürzel der aktuellen Sprache, z. B. ZH);
  2. klicken Sie auf den Button; das Dropdown-Menü listet alle 10 Sprachen auf;
  3. klicken Sie auf die Zielsprache (z. B. English oder 日本語);
  4. der Browser wechselt zur Version des aktuellen Artikels in der Zielsprache; Navigation, Seitenleiste, Inhaltsverzeichnis und Haupttext wechseln gemeinsam in die Zielsprache.

Beschriftete Darstellung des ausgeklappten Sprachwechsel-Dropdowns: ① Sprach-Button ② Sprachliste ③ aktuelle Sprache

Abbildung: Beschriftete Darstellung nach dem Klick auf den Sprach-Button auf der Seite „Mehrsprachigkeit & Sprachwechsel“. ① der Sprachumschalter rechts in der Kopfzeile; ② das ausgeklappte Dropdown-Menü mit allen 10 Sprachen (die Liste ist scrollbar); ③ die aktuell aktive Sprache (mit Häkchen markiert).

Schemadarstellung des Sprachwechsel-Mechanismus

Abbildung: Ablauf des Sprachwechsels. Beim Build wird für jede Sprache ein eigener Satz statischer Seiten erzeugt; ein Klick auf den Sprach-Button führt zur Version desselben Artikels in der Zielsprache. Fehlt für einzelne Seiten die Übersetzung, wird automatisch der Fallback auf Chinesisch (vereinfacht) angezeigt.

URL-Regeln

Die Seiten jeder Sprache haben ein eigenes URL-Präfix; derselbe Artikel unterscheidet sich zwischen den Sprachen nur durch das Präfix:

/canvas/i18n/          → Chinesisch, vereinfacht (Standardsprache, ohne Präfix)
/en/canvas/i18n/       → Englisch
/ja/canvas/i18n/       → Japanisch
/zh-tw/canvas/i18n/    → Chinesisch, traditionell
  • Die Sprachinformation ist direkt in der URL kodiert; die Seite nach dem Sprachwechsel lässt sich direkt als Lesezeichen speichern und teilen, und Suchmaschinen können sie sprachweise getrennt aufnehmen;
  • interne Links innerhalb der Seite (Navigation, Seitenleiste, Empfehlungslinks im Haupttext) erhalten automatisch das Präfix der aktuellen Sprache; wer innerhalb einer Sprache weiterliest, wird also nicht auf chinesische Seiten zurückgeworfen;
  • jede Sprachversion ist eine beim Build erzeugte, eigenständige statische Seite; das <html lang>-Attribut der Seite entspricht der Sprache, sodass Screenreader und Übersetzungswerkzeuge sie korrekt erkennen.

Was passiert bei fehlenden Übersetzungen?

Das System behandelt fehlende Übersetzungen nach der Fallback-Strategie „Rückgriff auf die Standardsprache“: Hat ein Dokument noch keine Übersetzung in einer Sprache, zeigt der Aufruf der Seite in dieser Sprache den Inhalt der Standardsprache Chinesisch (vereinfacht); der Rest der Seite (Navigation, Seitenleiste, Oberflächentexte) bleibt in der Zielsprache. Es erscheint weder ein 404-Fehler noch eine leere Seite.

Der Vorteil dieser Strategie: Neue Dokumente müssen nicht warten, bis die Übersetzungen in allen Sprachen fertig sind. Sie veröffentlichen zunächst die chinesische Version; sobald die Übersetzungen nachgereicht sind, genügt ein neuer Build.

Wie die Mehrsprachigkeit technisch funktioniert

Die Mehrsprachigkeit stützt sich auf die Internationalisierungsmechanismen von Astro und Starlight. Der Build-Ablauf:

  1. Inhaltsordner nach Sprachen getrennt: Die Dokumente der Standardsprache liegen unter src/content/docs/ (Chinesisch, vereinfacht), die anderen Sprachen unter src/content/docs/<Sprache>/; die Verzeichnisstruktur entspricht exakt der chinesischen, die englische Version von „Mehrsprachigkeit & Sprachwechsel“ liegt z. B. unter src/content/docs/en/canvas/i18n.md;
  2. alle Sprachseiten beim Build erzeugt: astro build liest die locales-Konfiguration aus astro.config.mjs und erzeugt für jede Sprache einen vollständigen Satz statischer Seiten;
  3. Oberflächentexte sprachweise gerendert: Oberflächentexte wie Kopfnavigation, Suchhinweise und Verzeichnistitel geben die Komponenten über getTranslation(key, lang) direkt beim Build in der jeweiligen Sprache aus; es gibt kein Skript, das zur Laufzeit Texte austauscht;
  4. interne Links im Haupttext automatisch lokalisiert: Das Plugin rehypeLocalizeInternalLinks in der Build-Pipeline versieht interne Links wie /canvas/xxx im übersetzten Haupttext automatisch mit dem Präfix der aktuellen Sprache;
  5. Volltextsuche sprachweise getrennt: Pagefind erstellt für jede Sprache einen eigenen Index; auf einer englischen Seite liefert die Suche nur englische Ergebnisse.
  6. Bilder im Text je Sprache automatisch zurückfallen： das Plugin rehypeLocalizeDiagramImages schreibt in Übersetzungen /images/canvas/<Datei> auf /images/canvas/<Sprache>/<Datei> um, die Sprachversionen liegen in public/images/canvas/<Sprache>/; fehlt eine Datei mit demselben Namen, bleibt das Original stehen – ein neues Bild muss also nicht sofort in allen 10 Sprachen vorliegen;
  7. Hinweisboxen und Fußnoten folgen der Seitensprache: rehypeLocalizeAsides und rehypeLocalizeFootnotes setzen die Titel der Hinweisboxen und die Fußnotentexte anhand des Sprachverzeichnisses der Quelldatei – Starlight erschließt die Sprache in remark über den absoluten Pfad, der lokale Build übergibt aber einen relativen Pfad, ohne diesen Schritt fiele alles auf Chinesisch zurück;
  8. hreflang und 404-Seite: nach dem Build ergänzt hreflangXDefault() je Seite einen hreflang="x-default"-Eintrag auf die vereinfacht-chinesische Fassung, und src/pages/404.astro nutzt dasselbe Wörterbuch für die Meldung in der Browsersprache; das Sprachmenü dort verweist auf die Startseite der jeweiligen Sprache.

Für Entwickler: Wie fügt man eine Sprache hinzu?

Am Beispiel des Hinzufügens von Italienisch (Italiano, Code it):

  1. Sprachroute registrieren: In den locales in astro.config.mjs den Eintrag it: { label: 'Italiano', lang: 'it' } ergänzen;
  2. Seitenleisten-Texte ergänzen: In derselben Datei in SIDEBAR_I18N für alle Gruppen und Einträge die it-Übersetzung nachtragen;
  3. Oberflächentexte ergänzen: In SUPPORTED_LANGUAGES in src/utils/i18n.ts die Sprache eintragen (Code, Name, Kürzel, URL-Präfix) und in UI_TRANSLATIONS die Oberflächentexte dieser Sprache vervollständigen;
  4. Dokumentinhalte übersetzen: Das Verzeichnis src/content/docs/it/ neu anlegen und die Übersetzungen gemäß der Verzeichnisstruktur der chinesischen Version ablegen. Noch nicht übersetzte Seiten zeigen vorerst den chinesischen Fallback und können nach und nach ergänzt werden; Wer auch Screenshots und Schaubilder übersetzen will, legt gleichnamige Dateien in public/images/canvas/it/ ab – die Seiten greifen automatisch darauf zu.
  5. neu bauen: pnpm run build ausführen; die Seiten der neuen Sprache und der Suchindex werden erzeugt. Nach dem Build prüfen node scripts/audit-i18n.mjs und node scripts/check-localized-images.mjs Übersetzungsstruktur und Bildreferenzen; beide Checks sind in CI Pflicht.

Für Entwickler: Wie fügt man Oberflächentexte hinzu oder ändert sie?

Fügen Sie bei neuen Oberflächenelementen die Texte in UI_TRANSLATIONS in src/utils/i18n.ts hinzu:

src/utils/i18n.ts
// Das Wörterbuch ist zweistufig nach „Sprache → Textschlüssel“ organisiert,
// entsprechend der Lesereihenfolge von getTranslation
export const UI_TRANSLATIONS: Record<string, Record<string, string>> = {
  // Schritt 1: Texte in der Standardsprache zh-CN hinzufügen
  // (fehlt ein Text, zeigt die Oberfläche als Fallback den Schlüsselnamen an)
  'zh-CN': {
    'nav.plugins': '插件生态',
    // ...übrige bereits vorhandene Texte
  },
  // Schritt 2: für andere Sprachen dieselben Schlüssel nachpflegen;
  // Sprachen ohne Eintrag fallen automatisch auf Chinesisch zurück
  en: {
    'nav.plugins': 'Plugins',
  },
  ja: {
    'nav.plugins': 'プラグイン',
  },
};

Rufen Sie anschließend in der Komponente getTranslation auf und übergeben Sie die aktuelle Sprache:

---
import { getLangFromLocale, getTranslation } from '../../utils/i18n';
const lang = getLangFromLocale(Astro.currentLocale);
---


<a href={localizedHref('/plugins/', lang)}>{getTranslation('nav.plugins', lang)}</a>

Die Texte werden beim Build als statischer Text in der jeweiligen Sprache gerendert; es entsteht kein Laufzeit-Overhead.