i18n

leadtype/i18n adds multi-locale support to the pipeline: locale-prefixed URLs, per-locale llms.txt/llms-full.txt/markdown mirrors/search/sitemaps, an i18n-manifest.json, and alternate-locale links for HTML heads. Enable it by adding i18n to your config; everything else is derived.

Config

docs.config.ts

import { defineDocsConfig } from "leadtype";

export default defineDocsConfig({
  product: { name: "My library", tagline: "..." },
  navigation: ["index"],
  i18n: {
    defaultLocale: "en",
    locales: ["en", "zh", { code: "fr", label: "Français", dir: "ltr" }],
    fallback: "default",
  },
});

Name	Type	Default	Description
`defaultLocale`	`string`	-	Locale served at the unprefixed docs root. Must be one of `locales`.
`locales`	`(string \| { code, label?, dir? })[]`	-	All locales. Shorthand string or an object with a display `label` and text `dir` ("ltr" \| "rtl").
`fallback`	`"default"`	-	How missing translations resolve. `"default"` (the only mode today) falls back to the default-locale page. Optional; defaults to `"default"`.

Validation (enforced by normalizeDocsI18nConfig, run during generate): locale codes must be URL-safe ([a-zA-Z0-9][a-zA-Z0-9_-]*), duplicates are rejected, and defaultLocale must appear in locales.

URL strategy

The default locale stays unprefixed; translated locales get a /{locale} segment after the docs prefix.

Source file	Locale	Page URL	Markdown mirror
`docs/quickstart.mdx`	`en` (default)	`/docs/quickstart`	`/docs/quickstart.md`
`docs/zh/quickstart.mdx`	`zh`	`/docs/zh/quickstart`	`/docs/zh/quickstart.md`
`docs/zh/guides/index.mdx`	`zh`	`/docs/zh/guides`	`/docs/zh/guides/index.md`

Helpers

All exported from leadtype/i18n:

Name	Type	Default	Description
`normalizeDocsI18nConfig`	`(config?) => NormalizedDocsI18nConfig \| undefined`	-	Validate and normalize config (string → { code }). Returns undefined when i18n is unset.
`listDocsLocales`	`(i18n?) => DocsLocale[]`	-	All locales, normalized. Empty when i18n is off.
`isDefaultLocale`	`(locale, i18n?) => boolean`	-	Whether a locale is the default.
`getDocsLocaleUrlPrefix`	`(locale, i18n?, docsUrlPrefix?) => string`	-	URL prefix for a locale, e.g. `/docs` (default) or `/docs/zh`.
`resolveDocsLocale`	`(pathname, i18n?, docsUrlPrefix?) => string \| undefined`	-	Infer the active locale from a request path; returns the default locale for unprefixed docs paths.
`stripLocaleFromDocsPath`	`(pathname, i18n?, docsUrlPrefix?) => string`	-	Remove the locale segment from a path.
`toLocalizedDocsUrlPath`	`(relativePath, locale, i18n?, mounts?) => string`	-	Build the page URL for a source file in a locale (mount-aware).
`toLocalizedMarkdownUrlPath`	`(relativePath, locale, i18n?, mounts?) => string`	-	Build the `.md` mirror URL for a locale.
`getAlternateLocaleLinks`	`(page, pagesByLocale, i18n?) => AlternateLocaleLink[]`	-	Alternate-locale links (hreflang) for a page, matched by logical path across locales.

Alternate-locale links

getAlternateLocaleLinks returns one entry per locale that has a matching page (same logical path), for rendering <link rel="alternate" hreflang> tags:

type AlternateLocaleLink = {
  locale: string;
  urlPath: string;
  label?: string;
  dir?: "ltr" | "rtl";
  /** true when this locale falls back to default-locale content. */
  isFallback: boolean;
};

i18n-manifest.json

Site-mode generate writes docs/i18n-manifest.json alongside the other artifacts. It lists every locale and the paths of that locale's generated files, so a runtime can serve the right llms.txt, search index, sitemap, and robots per locale.

type DocsI18nManifest = {
  version: 1;
  defaultLocale: string;
  locales: { code: string; label?: string; dir?: "ltr" | "rtl" }[];
  artifacts: {
    locale: string;
    urlPrefix: string; // "/docs" for default, "/docs/{locale}" otherwise
    llmsTxt?: string;
    llmsFullTxt?: string;
    searchIndex?: string;
    searchContent?: string;
    agentReadabilityManifest?: string;
    robotsTxt?: string;
    sitemapMd?: string;
    sitemapXml?: string;
  }[];
};

See Localize docs for the authoring layout and the end-to-end build.