Eine Dokumentationsseite lokalisieren

Ginko Docs dokumentiert zwei Sprachkonfigurationen: Englisch als einzige Sprache oder Englisch als Standardsprache mit deutscher Übersetzung. Wähle das Content-Layout in content.config.ts, und überlasse Nuxt i18n die Sprachdatensätze und Standardsprache in nuxt.config.ts. Beide Konfigurationen müssen dieselbe öffentliche URL abbilden. Die Beispiele verwenden den gemeinsamen site.json-Wert aus dem Schnellstart.

Eine rein englische Website konfigurieren

Lege englische Inhalte direkt unter content/docs/ ab:

Setze Englisch in beiden Konfigurationen ausdrücklich:

import { defineGinkoDocsConfig } from "@lupinum/ginko-docs/content";
import site from "./site.json" with { type: "json" };

export default defineGinkoDocsConfig({
  site,
  locales: ["en"],
  blog: false,
});

import site from "./site.json" with { type: "json" };

export default defineNuxtConfig({
  extends: ["@lupinum/ginko-docs"],
  site: { url: site.url },
  i18n: {
    baseUrl: site.url,
    defaultLocale: "en",
    locales: [{ code: "en", language: "en-US", name: "English" }],
  },
});

Englisch bleibt ohne Präfix, die Dokumentation beginnt daher unter /docs.

Deutsch hinzufügen

Bei einer zweisprachigen Website erhält jede Sprache einen eigenen Content-Stamm. Übersetze Ordner- und Dateinamen, behalte aber ihre numerischen Positionen bei:

Die übereinstimmende numerische Position gibt beiden Dateien eine gemeinsame Dokumentidentität. Ginko kann dadurch beim Sprachwechsel /docs/getting-started auf /de/dokumentation/erste-schritte abbilden.

import { defineGinkoDocsConfig } from "@lupinum/ginko-docs/content";
import site from "./site.json" with { type: "json" };

export default defineGinkoDocsConfig({
  site,
  locales: ["en", "de"],
  blog: false,
});

import site from "./site.json" with { type: "json" };

export default defineNuxtConfig({
  extends: ["@lupinum/ginko-docs"],
  site: { url: site.url },
  i18n: {
    baseUrl: site.url,
    defaultLocale: "en",
    strategy: "prefix_except_default",
    locales: [
      { code: "en", language: "en-US", name: "English" },
      { code: "de", language: "de-DE", name: "Deutsch" },
    ],
  },
  content: {
    i18n: {
      fallback: { de: ["en"] },
    },
  },
});

Der Fallback ist optional. Mit ihm rendert eine fehlende deutsche Seite die englische Variante unter der angefragten deutschen Route. Ohne Fallback liefert die fehlende Variante kein Dokument.

Übersetzte Bäume gekoppelt halten

Verwende für jedes Ordner- und Seitenpaar dieselbe numerische Position. Übersetze Titel, Beschreibungen, Slugs und Navigationsbezeichnungen; dupliziere eine englische Datei nicht an einer zweiten deutschen Position. Das Verschieben einer Datei ändert ihre Content-Identität und kann Sprachwechsel, Alternate-Links und sprachspezifische Suchergebnisse beeinträchtigen.

Verwende in beiden Sprachvarianten kanonische $docs/...-Referenzen mit englischen Segmenten. Ginko löst die Referenz beim Rendern für die aktive Sprache auf, während die Quelle ein stabiles Linkziel behält.