Internationalisierung (i18n)

Diese Seite dokumentiert, wie die Apothem-Dokumentationsseite mehrere Sprachen handhabt: die Sprachkohorte, die sie deklariert, den hreflang-Mechanismus, den sie ausgibt, ihre Rechts-nach-links-Darstellung und wie die Seiten jeder Sprache in das Routing eingebunden sind.

Zusammenfassung der EntscheidungenCopy Anchor Link

• Plattform: Next.js App Router + Fumadocs. Die Website wird aus site/ gebaut. Die Sprachkohorte ist in site/lib/i18n.ts deklariert, und der Mechanismus für Links auf alternative Sprachen liegt in site/lib/hreflang.ts.
• Sprachkohorte: zwölf Sprachen. Die Modern Dev Cohort aus zwölf Sprachen ist die kanonische Quelle der Wahrheit, mit Englisch als Quellsprache; jede der elf Zielsprachen ist maschinell aus dem englischen Seitenbestand vorbefüllt. Die menschliche Prüfung je Sprache ist im Gange, und fallbackLanguage: 'en' deckt jede Seite ab, die eine Sprache noch nicht verfasst hat.
• Routing je Sprache: in der gesamten Kohorte aktiviert. Jede Sprache ist in das Routing eingebunden und unter ihrem eigenen URL-Präfix erreichbar (/es/, /zh-cn/, …); Englisch wird im Stamm der Website ausgeliefert.
• hreflang-Mechanismus: aktiv. Jede Seite gibt einen Satz <link rel="alternate"> aus, der jede Sprache plus einen x-default-Fallback abdeckt, sodass Suchmaschinen den vollständigen Verbund alternativer Sprachen sehen. Die Links werden je Datei aus dem Dateisystem aufgelöst, sodass eine Seite in einer Sprache nur dann angekündigt wird, wenn diese Sprache sie hat.
• Rechts-nach-links-Darstellung: aktiv. Die gemeinsamen Stylesheets verwenden durchgängig logische CSS-Eigenschaften, sodass arabische Seiten unter dir="rtl" korrekt gerendert werden.
• Prüfung der Übersetzung: je Seite verfolgt. Maschinell vorbefüllte Sprachseiten werden ausgeliefert und tragen machineTranslated: true in ihrem Frontmatter, bis ein Mensch sie prüft; das Flag ist Metadatum zur Verfolgung der Prüfung, und die Seite zeigt es nicht an. Englisch ist der Fallback für jede Seite, die einer Sprache fehlt. Dass 80 % der Seiten einer Sprache geprüft sind, ist ein Prüfziel, keine Voraussetzung für die Veröffentlichung.
• Aktualität der Übersetzung: je Seite verfolgt. Jede übersetzte Seite erfasst den englischen Text, aus dem sie übersetzt wurde. Wenn sich die englische Seite später ändert, zeigt die übersetzte Seite einen einzeiligen Hinweis mit einem Link auf die englische Seite, die maßgeblich bleibt.

Die SprachkohorteCopy Anchor Link

Die Modern Dev Cohort deklariert zwölf Sprachen. Englisch wird im Stamm der Website ausgeliefert; die elf Zielsprachen sind jeweils maschinell aus dem englischen Seitenbestand vorbefüllt und liegen unter ihrem eigenen URL-Präfix, wobei fallbackLanguage: 'en' jede noch nicht verfasste Seite abdeckt.

Die Kohorte ist die einzige Quelle der Wahrheit; Änderungen an ihr laufen über eine bewusste Entscheidung, niemals über eine stille Bearbeitung.

Wie hreflang funktioniertCopy Anchor Link

site/lib/hreflang.ts baut die Zuordnung alternates.languages, die Next.js in den <head> jeder Seite rendert. Ihre Konstruktion befolgt eine Regel: Der Link einer Sprache auf die alternative Sprachversion wird nur dann ausgegeben, wenn diese Sprache die betreffende Seite verfasst hat, aufgelöst je Datei aus dem Dateisystem (site/lib/translated-pages.ts). Eine vollständig übersetzte Seite gibt daher den kompletten Verbund aus:

<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="es" href="https://apothem.ahmedgad.com/es/..." />
<link rel="alternate" hreflang="ar" href="https://apothem.ahmedgad.com/ar/..." dir="rtl" />
<!-- … one per cohort locale … -->
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />

Der canonical-Link der Seite ist stets ihre eigene URL — er verweist niemals über Sprachen hinweg.

Rechts-nach-links-DarstellungCopy Anchor Link

Arabisch ist die Rechts-nach-links-Sprache der Kohorte, und die Website rendert sie korrekt:

• Nur logische CSS-Eigenschaften. Die gemeinsamen Stylesheets und Komponenten verwenden logische Eigenschaften (margin-inline-start, padding-inline-end, text-align: start, inset-inline-start) statt physischer (margin-left, text-align: left). Logische Eigenschaften kehren sich unter dir="rtl" automatisch um, sodass dasselbe Stylesheet beide Richtungen korrekt bedient.
• Richtungsattribut. Arabische Seiten setzen dir="rtl" auf dem <html>-Element neben lang="ar".
• Bidirektionaler Inhalt. Zeichenketten mit gemischter Richtung — zum Beispiel ein englischer Befehl innerhalb eines arabischen Absatzes — werden in <bdi> eingeschlossen, sodass der eingebettete Links-nach-rechts-Abschnitt innerhalb des Rechts-nach-links-Flusses korrekt gerendert wird.

Eine Sprache hinzufügen oder aktualisierenCopy Anchor Link

Die Kohorte und das Routing werden von site/lib/i18n.ts gesteuert:

1. Verfassen Sie die Seite unter content/docs/<locale>/ als Spiegel der englischen Quelle.
2. Erfassen Sie den englischen Text, den sie übersetzt: Führen Sie aus site/ heraus node scripts/translation-sources.mjs --stamp <locale>/<path>.mdx aus; das schreibt den Hash der englischen Seite in das Frontmatter-Feld sourceHash der übersetzten Seite.
3. Bestätigen Sie, dass die Sprache in ROUTED_LOCALES aufgeführt ist (alle zwölf Sprachen der Kohorte werden heute geroutet).
4. Ihr hreflang-Link und ihre Routen werden automatisch aus dem Dateisystem aufgelöst.

Veraltete ÜbersetzungenCopy Anchor Link

Der sourceHash einer übersetzten Seite ist der Hash der englischen Seite, aus der sie übersetzt wurde; er umfasst das englische Frontmatter und die Prosa, nicht aber die generierten Tabellen, die der Referenzgenerator in allen Sprachen gleichzeitig neu schreibt. Zur Build-Zeit hasht die Website die aktuelle englische Seite; wenn sich die beiden unterscheiden, zeigt die übersetzte Seite einen Hinweis, dass sich die englische Seite seit der Übersetzung geändert hat, mit einem Link darauf. Führen Sie node scripts/translation-sources.mjs aus site/ heraus aus, um die veralteten Seiten je Sprache aufzulisten, und aktualisieren Sie dann jede Übersetzung und stempeln Sie sie wie in Schritt 2 oben. Eine Seite, die eine Sprache überhaupt nicht übersetzt hat, wird aus der englischen Quelle ausgeliefert und als englischer Text gekennzeichnet.

Englisch bleibt die Quelle der Wahrheit; jede übersetzte Seite spiegelt die Struktur, die Links und die Codebeispiele ihres englischen Gegenstücks wortgetreu.