Localize a documentation site

Ginko Docs supports two documented locale setups: English as the only locale, or English as the default locale with German translations. Select the content layout in content.config.ts, and let Nuxt i18n own the locale records and default locale in nuxt.config.ts. Both configurations must agree about the public URL. These examples reuse the shared site.json value from the quickstart.

Configure an English-only site

Keep English content directly under content/docs/:

Set English explicitly in both configurations:

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" }],
  },
});

English remains unprefixed, so documentation starts at /docs.

Add German

For a bilingual site, give each locale its own content root. Translate folder and file names, but keep their numeric positions aligned:

The matching numeric position gives both files one document identity. Ginko can then map /docs/getting-started to /de/dokumentation/erste-schritte when the reader changes language.

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"] },
    },
  },
});

The fallback is optional. With it, a missing German page renders the English variant at the requested German route. Without it, the missing variant returns no document.

Keep translated trees paired

Use the same numeric position for every pair of folders and pages. Translate titles, descriptions, slugs, and navigation labels; do not duplicate an English file under a second German position. A moved file changes its content identity and can break language switching, alternate links, and locale-specific search results.

Use canonical $docs/... references with English segments in both language variants. Ginko resolves the reference for the active locale while the source keeps one stable link target.