create-zudo-doc 5.14.0 → 5.15.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `create-zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.15.0] - 2026-09-01
+
+### Features
+
+- Added one ordered locale-plan contract across the API, CLI, presets, prompts, scaffold output, and generated guidance, allowing new projects to select and emit any supported set of locales. (`10e34ca0`, `5a990248`, `c9543772`)
+
+### Bug Fixes
+
+- Newly generated multi-locale projects now localize generated Claude/Codex resource routes by default instead of keeping them limited to the default locale. (`26ecad11`)
+
+### Other Changes
+
+- Updated newly generated projects to use the zfb 2.14.2 package family. (`1c1f8f26`)
+
 ## [5.14.0] - 2026-08-31
 
 ### Features

package/README.md

@@ -35,13 +35,49 @@ pnpm create zudo-doc my-docs --yes
 # Fully specified, non-interactive
 pnpm create zudo-doc my-docs \
   --lang ja \
+  --additional-langs en,de \
   --scheme "Default Dark" \
-  --no-i18n \
   --search \
   --pm pnpm \
   --install
 ```
 
+### Locales and translations
+
+`--lang` selects the primary locale. Its pages use the unprefixed
+`/docs/...` routes and `src/content/docs/`. Add any number of additional
+locales, in the order shown by the language switcher, with
+`--additional-langs <code,...>`:
+
+```bash
+pnpm create zudo-doc my-docs \
+  --lang en \
+  --additional-langs ja,de \
+  --yes
+```
+
+An omitted or blank list creates a single-locale project. The same rule
+applies to a preset that omits `additionalLangs`; an explicit non-empty list
+is normalized to lowercase, validates each code for safe URL/path use, rejects
+duplicates and the primary code, and creates `src/content/docs-<code>/` plus
+the corresponding `/<code>/docs/...` routes. A legacy preset containing only
+`i18n: true` keeps compatibility inference (`ja` for primary `en`, otherwise
+`en`).
+
+CLI locale flags replace the preset list rather than merging with it. An
+explicit `--additional-langs` also enables i18n; if it overrides
+`--no-i18n`, the CLI prints a warning so the precedence is visible.
+
+The generated starter uses Japanese prose for `ja` and English placeholder
+prose for every other additional locale. Translate those pages before
+publishing. Labels are configuration-driven: the switcher uses each locale's
+configured `label` and map order, so custom codes and labels are not tied to
+hard-coded `JP` or `JA` links.
+
+Built-in UI translations resolve in this order:
+
+`requested locale → configured default locale → package English → raw UI-string key`
+
 ## Options
 
 ### Project basics
@@ -50,6 +86,7 @@ pnpm create zudo-doc my-docs \
 |------|-------------|---------|
 | `[project-name]` | Project name (positional arg or `--name`) | prompted |
 | `--lang <code>` | Default language: `en`, `ja`, `zh-cn`, `zh-tw`, `ko`, `es`, `fr`, `de`, `pt` | `en` |
+| `--additional-langs <a,b>` | Ordered additional locale codes; implies i18n and replaces a preset list | none |
 | `--pm <manager>` | Package manager: `pnpm`, `npm`, `yarn`, `bun` | detected |
 | `--[no-]install` | Install dependencies after scaffolding | prompted |
 | `-y, --yes` | Use defaults for all unspecified options, skip prompts | — |
@@ -72,7 +109,7 @@ Each feature has a `--[no-]<flag>` form. Passing `--feature` enables it; `--no-f
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--[no-]i18n` | Multi-language support (adds a secondary locale) | off |
+| `--[no-]i18n` | Legacy multi-language toggle; with no explicit list, infers one additional locale | off |
 | `--[no-]search` | Full-text search | on |
 | `--[no-]sidebar-filter` | Real-time sidebar filter | on |
 | `--[no-]image-enlarge` | Click-to-enlarge for oversized images | on |
@@ -140,6 +177,7 @@ import { createZudoDoc } from "create-zudo-doc";
 await createZudoDoc({
   projectName: "my-docs",
   defaultLang: "en",
+  additionalLangs: ["ja", "de"],
   colorSchemeMode: "single",
   singleScheme: "Default Dark",
   features: ["search", "sidebarFilter", "tagGovernance"],

package/dist/api.d.ts

@@ -1,9 +1,12 @@
 import type { PresetHeaderRightItem, PresetMetaTagsConfig } from "./preset.js";
+export { resolveLocalePlan, type LocalePlan, type LocalePlanInput, } from "./locale-plan.js";
 export type { UserChoices } from "./prompts.js";
 export interface CreateOptions {
     projectName: string;
     /** Default language code (default: "en") */
     defaultLang?: string;
+    /** Ordered additional locale codes. A non-empty list implies i18n. */
+    additionalLangs?: string[];
     colorSchemeMode: "single" | "light-dark";
     singleScheme?: string;
     lightScheme?: string;

package/dist/api.js

@@ -3,6 +3,8 @@ import { SINGLE_SCHEMES, THEME_PACKS } from "./constants.js";
 import { parseChangelogPackages, validateChangelogPackages, validateHeaderRightItems, validateMetaTags, } from "./preset.js";
 import { scaffold } from "./scaffold.js";
 import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
+import { resolveLocalePlan } from "./locale-plan.js";
+export { resolveLocalePlan, } from "./locale-plan.js";
 export async function createZudoDoc(options) {
     const { install = false, git = false, ...rest } = options;
     const nameError = validateProjectName(rest.projectName);
@@ -52,9 +54,18 @@ export async function createZudoDoc(options) {
             throw new Error(err);
         changelogPackages = parseChangelogPackages(changelogPackages);
     }
+    const localePlan = resolveLocalePlan({
+        defaultLang: rest.defaultLang ?? "en",
+        additionalLangs: rest.additionalLangs,
+        i18n: rest.features.includes("i18n"),
+    });
     const choices = {
         ...rest,
-        defaultLang: rest.defaultLang ?? "en",
+        defaultLang: localePlan.defaultLang,
+        additionalLangs: rest.additionalLangs === undefined ? undefined : localePlan.additionalLangs,
+        features: localePlan.i18n
+            ? [...new Set([...rest.features, "i18n"])]
+            : rest.features.filter((feature) => feature !== "i18n"),
         changelogPackages,
     };
     await scaffold(choices);

package/dist/claude-md-gen.d.ts

@@ -1,4 +1,5 @@
 import type { UserChoices } from "./prompts.js";
+import type { LocalePlan } from "./locale-plan.js";
 /**
  * Generate the per-project `CLAUDE.md` (minimal-scaffold shape, epic
  * zudolab/zudo-doc#2651, Wave 6 #2660). Rewritten from scratch — the old
@@ -7,4 +8,4 @@ import type { UserChoices } from "./prompts.js";
  * longer exists. The scaffolded project is now ~13 files; almost
  * everything referenced here lives in `node_modules/@takazudo/zudo-doc`.
  */
-export declare function generateCLAUDEFile(choices: UserChoices): string;
+export declare function generateCLAUDEFile(choices: UserChoices, localePlan?: LocalePlan): string;

package/dist/claude-md-gen.js

@@ -1,4 +1,5 @@
-import { capitalize, pmRunCommand } from "./utils.js";
+import { resolveLocalePlan } from "./locale-plan.js";
+import { capitalize, getLangLabel, pmRunCommand } from "./utils.js";
 /**
  * Generate the per-project `CLAUDE.md` (minimal-scaffold shape, epic
  * zudolab/zudo-doc#2651, Wave 6 #2660). Rewritten from scratch — the old
@@ -7,9 +8,30 @@ import { capitalize, pmRunCommand } from "./utils.js";
  * longer exists. The scaffolded project is now ~13 files; almost
  * everything referenced here lives in `node_modules/@takazudo/zudo-doc`.
  */
-export function generateCLAUDEFile(choices) {
+export function generateCLAUDEFile(choices, localePlan = resolveLocalePlan({
+    defaultLang: choices.defaultLang,
+    additionalLangs: choices.additionalLangs,
+    i18n: choices.features.includes("i18n"),
+    i18nExplicitlyDisabled: choices.explicitlyDisabledFeatures?.includes("i18n"),
+})) {
     const siteName = capitalize(choices.projectName.replace(/-/g, " "));
     const lines = [];
+    const localeDisplayName = (locale) => {
+        if (locale === "en")
+            return "English";
+        if (locale === "ja")
+            return "Japanese";
+        return getLangLabel(locale);
+    };
+    const localeStarterNote = (locale) => {
+        if (locale === "ja")
+            return "Japanese starter prose";
+        if (locale === "en")
+            return "English starter prose";
+        return "English placeholder prose pending translation";
+    };
+    const defaultLocaleLabel = localeDisplayName(localePlan.defaultLang);
+    const additionalLocales = localePlan.i18n ? localePlan.additionalLangs : [];
     lines.push(`# ${siteName}`);
     lines.push(``);
     lines.push(`Documentation site built with [zudo-doc](https://github.com/zudolab/zudo-doc) — a zfb-based documentation framework with MDX, Tailwind CSS v4, and Preact islands. This project is intentionally minimal: one config file (\`zfb.config.ts\`) plus markdown content — layout, chrome, and islands all ship from \`@takazudo/zudo-doc\` in \`node_modules\`.`);
@@ -49,16 +71,17 @@ export function generateCLAUDEFile(choices) {
     lines.push(`pages/`);
     lines.push(`├── index.tsx             # 1-line re-export of the package home route`);
     lines.push(`└── docs/[[...slug]].tsx  # self-contained doc-route stub (required for \`${pm} dev\`)`);
-    if (choices.features.includes("i18n")) {
+    if (localePlan.i18n) {
         lines.push(`  [locale]/docs/[[...slug]].tsx  # same, for non-default locales`);
     }
     lines.push(`src/`);
     lines.push(`├── chrome-bindings.tsx   # optional typed primary chrome / named header / MDX bindings`);
     lines.push(`├── content/`);
-    lines.push(`│   └── docs/             # MDX content (this project's showcase docs)`);
-    if (choices.features.includes("i18n")) {
-        const secondaryLang = choices.defaultLang === "ja" ? "en" : "ja";
-        lines.push(`│   └── docs-${secondaryLang}/         # ${secondaryLang === "ja" ? "Japanese" : "English"} MDX content (mirrors docs/)`);
+    const defaultBranch = additionalLocales.length === 0 ? "└──" : "├──";
+    lines.push(`│   ${defaultBranch} docs/             # ${defaultLocaleLabel} (default) MDX content (routes at /docs/; ${localeStarterNote(localePlan.defaultLang)})`);
+    for (const [index, locale] of additionalLocales.entries()) {
+        const branch = index === additionalLocales.length - 1 ? "└──" : "├──";
+        lines.push(`│   ${branch} docs-${locale}/         # ${localeDisplayName(locale)} MDX content (routes at /${locale}/docs/; ${localeStarterNote(locale)})`);
     }
     lines.push(`└── styles/`);
     lines.push(`    └── global.css        # @import chain + a token-override slot — that's it`);
@@ -105,15 +128,15 @@ export function generateCLAUDEFile(choices) {
     lines.push(`Admonitions (above), tabbed content (\`<Tabs>\` / \`<TabItem>\`, \`<CodeGroup>\`), and block math (\`<MathBlock>\`) work the same way — no import. Full reference: https://zudo-doc.takazudomodular.com/docs/components/`);
     lines.push(``);
     // i18n section
-    if (choices.features.includes("i18n")) {
-        const secondaryLang = choices.defaultLang === "ja" ? "en" : "ja";
-        const defaultLabel = choices.defaultLang === "ja" ? "Japanese" : "English";
-        const secondaryLabel = secondaryLang === "ja" ? "Japanese" : "English";
+    if (localePlan.i18n) {
         lines.push(`## i18n`);
         lines.push(``);
-        lines.push(`- ${defaultLabel} (default): \`/docs/...\` — content in \`src/content/docs/\``);
-        lines.push(`- ${secondaryLabel}: \`/${secondaryLang}/docs/...\` — content in \`src/content/docs-${secondaryLang}/\``);
-        lines.push(`- ${secondaryLabel} docs should mirror the ${defaultLabel} directory structure`);
+        lines.push(`- ${defaultLocaleLabel} (default, \`${localePlan.defaultLang}\`): \`/docs/...\` — content in \`src/content/docs/\` (${localeStarterNote(localePlan.defaultLang)})`);
+        for (const locale of additionalLocales) {
+            lines.push(`- ${localeDisplayName(locale)} (\`${locale}\`): \`/${locale}/docs/...\` — content in \`src/content/docs-${locale}/\` (${localeStarterNote(locale)})`);
+        }
+        lines.push(`- Every additional-locale directory should mirror the default directory structure`);
+        lines.push(`- The \`ja\` locale, when configured, receives Japanese starter prose and uses Japanese translation conventions. Other non-EN locale directories currently receive English placeholder prose pending translation; do not assume they are already translated.`);
         lines.push(`- Both \`pages/docs/[[...slug]].tsx\` and \`pages/[locale]/docs/[[...slug]].tsx\` are self-contained doc-route stubs shipped by the generator as explicit host-owned seams. zfb 2.13.1 also renders package-injected dynamic routes in dev; keep these files so the generated project retains route ownership and customization.`);
         lines.push(``);
     }

package/dist/cli.d.ts

@@ -1,6 +1,7 @@
 export interface CliArgs {
     name?: string;
     lang?: string;
+    additionalLangs?: string[];
     colorSchemeMode?: "single" | "light-dark";
     scheme?: string;
     lightScheme?: string;
@@ -43,6 +44,8 @@ export interface CliArgs {
     yes?: boolean;
     help?: boolean;
 }
+/** Presets are the base layer; an explicitly supplied CLI list replaces it. */
+export declare function layerAdditionalLangs(presetValue: string[] | undefined, cliValue: string[] | undefined): string[] | undefined;
 export declare function parseArgs(argv?: string[]): CliArgs;
 export declare function printHelp(): void;
 export declare function validateArgs(args: CliArgs): string | null;

package/dist/cli.js

@@ -3,11 +3,17 @@ import pc from "picocolors";
 import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS, THEME_PACKS } from "./constants.js";
 import { parseChangelogPackages, validateChangelogPackages, } from "./preset.js";
 import { validateProjectName } from "./utils.js";
+import { resolveLocalePlan } from "./locale-plan.js";
+/** Presets are the base layer; an explicitly supplied CLI list replaces it. */
+export function layerAdditionalLangs(presetValue, cliValue) {
+    return cliValue === undefined ? presetValue : cliValue;
+}
 export function parseArgs(argv = process.argv.slice(2)) {
     const raw = minimist(argv, {
         string: [
             "name",
             "lang",
+            "additional-langs",
             "color-scheme-mode",
             "scheme",
             "light-scheme",
@@ -42,6 +48,10 @@ export function parseArgs(argv = process.argv.slice(2)) {
     }
     if (raw.lang)
         args.lang = raw.lang;
+    if (raw["additional-langs"] !== undefined) {
+        const value = raw["additional-langs"];
+        args.additionalLangs = (typeof value === "string" ? value : String(value)).split(",");
+    }
     if (raw["color-scheme-mode"])
         args.colorSchemeMode = raw["color-scheme-mode"];
     if (raw.scheme)
@@ -96,6 +106,7 @@ ${pc.bold("Options:")}
   --name <name>                Project name (or first positional arg)
   --lang <code>                Default language (${langList})
                                Default: en
+  --additional-langs <a,b>     Additional locale codes (ordered; implies i18n)
   --color-scheme-mode <mode>   single | light-dark
   --scheme <name>              Color scheme (single mode)
   --light-scheme <name>        Light scheme (light-dark mode)
@@ -137,6 +148,22 @@ export function validateArgs(args) {
             return `Invalid language "${args.lang}". Supported: ${validLangs.join(", ")}`;
         }
     }
+    // A preset may supply the primary locale, so defer cross-field validation
+    // until the layered choices reach runPrompts() when --lang is omitted.
+    if (args.additionalLangs !== undefined &&
+        (args.preset === undefined || args.lang !== undefined)) {
+        try {
+            resolveLocalePlan({
+                defaultLang: args.lang ?? "en",
+                additionalLangs: args.additionalLangs,
+                i18n: args.i18n ?? false,
+                i18nExplicitlyDisabled: args.i18n === false,
+            });
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+    }
     if (args.colorSchemeMode && !["single", "light-dark"].includes(args.colorSchemeMode)) {
         return `Invalid color-scheme-mode "${args.colorSchemeMode}". Must be "single" or "light-dark"`;
     }

package/dist/compose.d.ts

@@ -1,4 +1,5 @@
 import type { UserChoices } from "./prompts.js";
+import type { LocalePlan } from "./locale-plan.js";
 /** A single injection into a shared file at an anchor point. */
 export interface Injection {
     /** Target file path relative to project root */
@@ -29,13 +30,13 @@ export interface FeatureDefinition {
      * Post-processing hook for complex transformations that cannot be expressed
      * as simple file copies or anchor injections (e.g. i18n page patching).
      */
-    postProcess?: (targetDir: string, choices: UserChoices) => Promise<void>;
+    postProcess?: (targetDir: string, choices: UserChoices, localePlan?: LocalePlan) => Promise<void>;
 }
 /**
  * A function that returns a FeatureDefinition based on user choices.
  * This allows injections to be conditional on other choices.
  */
-export type FeatureModule = (choices: UserChoices) => FeatureDefinition;
+export type FeatureModule = (choices: UserChoices, localePlan?: LocalePlan) => FeatureDefinition;
 /**
  * Apply a list of injections to files in the target directory.
  *
@@ -62,7 +63,7 @@ export declare function copyFeatureFiles(featureFilesDir: string, targetDir: str
  * Resolve which features are selected based on UserChoices.
  * Handles special cases like the footer pseudo-feature.
  */
-export declare function resolveSelectedFeatures(choices: UserChoices, featureModules: Record<string, FeatureModule>): FeatureDefinition[];
+export declare function resolveSelectedFeatures(choices: UserChoices, featureModules: Record<string, FeatureModule>, localePlan?: LocalePlan): FeatureDefinition[];
 /**
  * Validate that all feature dependencies are satisfied.
  * Throws if a selected feature depends on one that isn't selected.
@@ -96,4 +97,4 @@ export declare const ANCHOR_FILES: string[];
  * 5. Run post-processing hooks
  * 6. Clean up unused anchors
  */
-export declare function composeFeatures(targetDir: string, choices: UserChoices, featureModules: Record<string, FeatureModule>, featuresDir: string): Promise<void>;
+export declare function composeFeatures(targetDir: string, choices: UserChoices, featureModules: Record<string, FeatureModule>, featuresDir: string, localePlan?: LocalePlan): Promise<void>;

package/dist/compose.js

@@ -120,7 +120,7 @@ export async function copyFeatureFiles(featureFilesDir, targetDir) {
  * Resolve which features are selected based on UserChoices.
  * Handles special cases like the footer pseudo-feature.
  */
-export function resolveSelectedFeatures(choices, featureModules) {
+export function resolveSelectedFeatures(choices, featureModules, localePlan) {
     const selected = [];
     for (const [name, moduleFn] of Object.entries(featureModules)) {
         // Special case: footer is activated by footerNavGroup, footerCopyright,
@@ -129,12 +129,12 @@ export function resolveSelectedFeatures(choices, featureModules) {
             if (choices.features.includes("footerNavGroup") ||
                 choices.features.includes("footerCopyright") ||
                 choices.features.includes("footerTaglist")) {
-                selected.push(moduleFn(choices));
+                selected.push(moduleFn(choices, localePlan));
             }
             continue;
         }
         if (choices.features.includes(name)) {
-            selected.push(moduleFn(choices));
+            selected.push(moduleFn(choices, localePlan));
         }
     }
     return selected;
@@ -182,9 +182,9 @@ export const ANCHOR_FILES = [];
  * 5. Run post-processing hooks
  * 6. Clean up unused anchors
  */
-export async function composeFeatures(targetDir, choices, featureModules, featuresDir) {
+export async function composeFeatures(targetDir, choices, featureModules, featuresDir, localePlan) {
     // 1. Resolve
-    const features = resolveSelectedFeatures(choices, featureModules);
+    const features = resolveSelectedFeatures(choices, featureModules, localePlan);
     const selectedNames = new Set(features.map((f) => f.name));
     // 2. Validate
     validateDependencies(features, selectedNames);
@@ -202,7 +202,7 @@ export async function composeFeatures(targetDir, choices, featureModules, featur
     // 5. Post-processing
     for (const feature of features) {
         if (feature.postProcess) {
-            await feature.postProcess(targetDir, choices);
+            await feature.postProcess(targetDir, choices, localePlan);
         }
     }
     // 6. Clean up unused anchors

package/dist/constants.js

@@ -187,7 +187,7 @@ export const FEATURES = [
     {
         value: "i18n",
         label: "i18n (multi-language)",
-        hint: "Add a secondary language",
+        hint: "Configure additional locales",
         default: false,
         cliFlag: "i18n",
     },

package/dist/features/claude-resources.d.ts

@@ -5,7 +5,8 @@ import type { FeatureModule } from "../compose.js";
  * Fully plugin-owned (`@takazudo/zudo-doc/plugins/claude-resources`,
  * `zudoDocPreset()` wires it whenever `settings.claudeResources` is
  * truthy). Generation is package-owned. This feature's touch points are now
- * just: `claudeResources` + `defaultLocaleOnlyPrefixes` fields
- * (`zfb-config-gen.ts`).
+ * just the `claudeResources` field (`zfb-config-gen.ts`). Resource routes are
+ * localized by default; projects can opt selected paths out through the
+ * general-purpose `defaultLocaleOnlyPrefixes` setting.
  */
 export declare const claudeResourcesFeature: FeatureModule;

package/dist/features/claude-resources.js

@@ -4,8 +4,9 @@
  * Fully plugin-owned (`@takazudo/zudo-doc/plugins/claude-resources`,
  * `zudoDocPreset()` wires it whenever `settings.claudeResources` is
  * truthy). Generation is package-owned. This feature's touch points are now
- * just: `claudeResources` + `defaultLocaleOnlyPrefixes` fields
- * (`zfb-config-gen.ts`).
+ * just the `claudeResources` field (`zfb-config-gen.ts`). Resource routes are
+ * localized by default; projects can opt selected paths out through the
+ * general-purpose `defaultLocaleOnlyPrefixes` setting.
  */
 export const claudeResourcesFeature = () => ({
     name: "claudeResources",

package/dist/features/codex-resources.d.ts

@@ -5,7 +5,8 @@ import type { FeatureModule } from "../compose.js";
  * Fully plugin-owned (`@takazudo/zudo-doc/plugins/codex-resources`,
  * `zudoDocPreset()` wires it whenever `settings.codexResources` is
  * truthy). Generation is package-owned. This feature's touch points are now
- * just: `codexResources` + `defaultLocaleOnlyPrefixes` fields
- * (`zfb-config-gen.ts`).
+ * just the `codexResources` field (`zfb-config-gen.ts`). Resource routes are
+ * localized by default; projects can opt selected paths out through the
+ * general-purpose `defaultLocaleOnlyPrefixes` setting.
  */
 export declare const codexResourcesFeature: FeatureModule;

package/dist/features/codex-resources.js

@@ -4,8 +4,9 @@
  * Fully plugin-owned (`@takazudo/zudo-doc/plugins/codex-resources`,
  * `zudoDocPreset()` wires it whenever `settings.codexResources` is
  * truthy). Generation is package-owned. This feature's touch points are now
- * just: `codexResources` + `defaultLocaleOnlyPrefixes` fields
- * (`zfb-config-gen.ts`).
+ * just the `codexResources` field (`zfb-config-gen.ts`). Resource routes are
+ * localized by default; projects can opt selected paths out through the
+ * general-purpose `defaultLocaleOnlyPrefixes` setting.
  */
 export const codexResourcesFeature = () => ({
     name: "codexResources",

package/dist/features/i18n.d.ts

@@ -3,7 +3,7 @@ import type { FeatureModule } from "../compose.js";
  * i18n feature — gates the locale-prefixed page set.
  *
  * Locked manifest (#2653 Decision 4, i18n addendum): "i18n ON adds
- * `pages/[locale]/docs/[[...slug]].tsx` (a second doc stub, locale variant)
+ * `pages/[locale]/docs/[[...slug]].tsx` (the additional-locale doc route stub)
  * … No other pages." That ONE self-contained stub — retained as an explicit
  * host-owned route seam; zfb 2.13.1 also serves injected dynamic routes in dev —
  * is shipped under `templates/features/i18n/files/pages/[locale]/docs/`
@@ -15,7 +15,7 @@ import type { FeatureModule } from "../compose.js";
  *
  * No injections: the stub iterates `settings.locales` at build/request
  * time, so no postProcess regex patching is required for non-default
- * languages. Secondary-language content mirrors under
+ * locales. Additional-locale content mirrors under
  * `src/content/docs-<lang>/` are seeded by `scaffold.ts`.
  *
  * Loud-failure check: per spec-lock Decision 8 (#1737), abort scaffolding

package/dist/features/i18n.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "url";
  * i18n feature — gates the locale-prefixed page set.
  *
  * Locked manifest (#2653 Decision 4, i18n addendum): "i18n ON adds
- * `pages/[locale]/docs/[[...slug]].tsx` (a second doc stub, locale variant)
+ * `pages/[locale]/docs/[[...slug]].tsx` (the additional-locale doc route stub)
  * … No other pages." That ONE self-contained stub — retained as an explicit
  * host-owned route seam; zfb 2.13.1 also serves injected dynamic routes in dev —
  * is shipped under `templates/features/i18n/files/pages/[locale]/docs/`
@@ -17,7 +17,7 @@ import { fileURLToPath } from "url";
  *
  * No injections: the stub iterates `settings.locales` at build/request
  * time, so no postProcess regex patching is required for non-default
- * languages. Secondary-language content mirrors under
+ * locales. Additional-locale content mirrors under
  * `src/content/docs-<lang>/` are seeded by `scaffold.ts`.
  *
  * Loud-failure check: per spec-lock Decision 8 (#1737), abort scaffolding

package/dist/features/tag-governance.js

@@ -1,6 +1,6 @@
 import fs from "fs-extra";
 import path from "path";
-import { getSecondaryLang } from "../utils.js";
+import { resolveLocalePlan } from "../locale-plan.js";
 /**
  * Tag governance feature.
  *
@@ -8,18 +8,27 @@ import { getSecondaryLang } from "../utils.js";
  * feeds zfb while its default TagCliConfig export feeds both package-owned
  * bins through an explicit `--config` package-script argument.
  */
-export const tagGovernanceFeature = (choices) => ({
+export const tagGovernanceFeature = (choices, localePlan) => ({
     name: "tagGovernance",
     injections: [],
     postProcess: async (targetDir) => {
         const vocabPath = path.join(targetDir, "src/config/tag-vocabulary.ts");
         if (!(await fs.pathExists(vocabPath))) {
-            const contentDirs = choices.features.includes("i18n")
-                ? `[
-  "src/content/docs",
-  "src/content/docs-${getSecondaryLang(choices.defaultLang)}",
-]`
-                : `["src/content/docs"]`;
+            // `scaffold()` resolves the locale plan once and threads it through
+            // feature composition. Keep the fallback for direct FeatureModule
+            // callers (e.g. package consumers/tests) while ensuring normalization
+            // and legacy inference still have one canonical implementation.
+            const plan = localePlan ??
+                resolveLocalePlan({
+                    defaultLang: choices.defaultLang,
+                    additionalLangs: choices.additionalLangs,
+                    i18n: choices.features.includes("i18n"),
+                    i18nExplicitlyDisabled: choices.explicitlyDisabledFeatures?.includes("i18n"),
+                });
+            const contentDirs = [
+                "src/content/docs",
+                ...plan.additionalLangs.map((locale) => `src/content/docs-${locale}`),
+            ];
             await fs.outputFile(vocabPath, `import type { TagCliConfig } from "@takazudo/zudo-doc/tags-audit";
 import type { TagVocabularyEntry } from "@takazudo/zudo-doc/settings";
 
@@ -31,7 +40,7 @@ export const tagVocabulary: TagVocabularyEntry[] = [];
 // Package scripts pass this module to the package-owned audit/suggest bins.
 // Paths are resolved from the project root.
 const tagCliConfig = {
-  contentDirs: ${contentDirs},
+  contentDirs: ${JSON.stringify(contentDirs, null, 2)},
   vocabulary: tagVocabulary,
   governance: "warn",
   vocabularyActive: true,

package/dist/index.js

@@ -1,7 +1,7 @@
 import path from "path";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { parseArgs, printHelp, validateArgs } from "./cli.js";
+import { layerAdditionalLangs, parseArgs, printHelp, validateArgs, } from "./cli.js";
 import { FEATURES } from "./constants.js";
 import { loadPreset } from "./preset.js";
 import { runPrompts } from "./prompts.js";
@@ -40,6 +40,7 @@ async function main() {
         prefilled.projectName = args.name;
     if (args.lang)
         prefilled.defaultLang = args.lang;
+    prefilled.additionalLangs = layerAdditionalLangs(prefilled.additionalLangs, args.additionalLangs);
     if (args.colorSchemeMode)
         prefilled.colorSchemeMode = args.colorSchemeMode;
     if (args.scheme) {

package/dist/locale-plan.d.ts

@@ -0,0 +1,20 @@
+export interface LocalePlanInput {
+    defaultLang: string;
+    additionalLangs?: readonly string[];
+    i18n: boolean;
+    /** Whether the original input explicitly contained `--no-i18n`. */
+    i18nExplicitlyDisabled?: boolean;
+}
+export interface LocalePlan {
+    defaultLang: string;
+    additionalLangs: string[];
+    i18n: boolean;
+    /** A non-empty explicit list won over an explicit `--no-i18n`. */
+    overridesExplicitDisable: boolean;
+}
+/**
+ * Resolve every locale input path to one canonical, filesystem-safe plan.
+ * This function is pure and is the sole owner of locale normalization,
+ * validation, legacy inference, and explicit-list precedence.
+ */
+export declare function resolveLocalePlan(input: LocalePlanInput): LocalePlan;

package/dist/locale-plan.js

@@ -0,0 +1,58 @@
+/**
+ * A locale code is also used as a directory and URL-path segment. Keep this
+ * grammar deliberately smaller than the full BCP 47 grammar: an ASCII
+ * language followed by optional ASCII alphanumeric subtags.
+ */
+const LOCALE_RE = /^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/;
+function normalizeLocale(value, field) {
+    if (typeof value !== "string") {
+        throw new Error(`${field} must be a string`);
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!LOCALE_RE.test(normalized)) {
+        throw new Error(`Invalid ${field} ${JSON.stringify(value)}. Locale codes must match /^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/`);
+    }
+    return normalized;
+}
+/**
+ * Resolve every locale input path to one canonical, filesystem-safe plan.
+ * This function is pure and is the sole owner of locale normalization,
+ * validation, legacy inference, and explicit-list precedence.
+ */
+export function resolveLocalePlan(input) {
+    const defaultLang = normalizeLocale(input.defaultLang, "defaultLang");
+    if (input.additionalLangs === undefined) {
+        const additionalLangs = input.i18n
+            ? [defaultLang === "en" ? "ja" : "en"]
+            : [];
+        return {
+            defaultLang,
+            additionalLangs,
+            i18n: input.i18n,
+            overridesExplicitDisable: false,
+        };
+    }
+    if (!Array.isArray(input.additionalLangs)) {
+        throw new Error("additionalLangs must be an array");
+    }
+    if (input.additionalLangs.length === 0) {
+        throw new Error("additionalLangs must contain at least one locale");
+    }
+    const additionalLangs = input.additionalLangs.map((locale, index) => normalizeLocale(locale, `additionalLangs[${index}]`));
+    const seen = new Set();
+    for (const locale of additionalLangs) {
+        if (locale === defaultLang) {
+            throw new Error(`additionalLangs must not include defaultLang ${JSON.stringify(defaultLang)}`);
+        }
+        if (seen.has(locale)) {
+            throw new Error(`Duplicate locale ${JSON.stringify(locale)} in additionalLangs`);
+        }
+        seen.add(locale);
+    }
+    return {
+        defaultLang,
+        additionalLangs,
+        i18n: true,
+        overridesExplicitDisable: input.i18nExplicitlyDisabled === true,
+    };
+}