Multilingual content locale suffix pipeline

Definition

A locale suffix is a storage convention that appends a language code to the end of a markdown filename — for example .en.md or .ja.md — so documents that share the same slug but differ only by locale live side by side. Files without a suffix are treated as the default locale (e.g. ko).

When my-article.md (ko), my-article.en.md, and my-article.ja.md coexist under the same my-article slug, href, canonical, and hreflang can share the slug axis and keep multilingual sitemaps simple.

Why it matters

Splitting content into locale-specific folders like content/en/ and content/ja/ forks category paths, internal links, and build scripts, which raises maintenance cost. The suffix approach keeps the directory layout unchanged and adds locale as a separate data axis.

However, if locale lives only in filenames while DB primary keys and search index ids stay as type:slug, you get silent row collisions, zero-result search hydration, and MiniSearch duplicate-id exceptions. Locale must be threaded consistently from filename → types → SQLite id → search-index id → API queries.

How it works

1. Loader: When globbing, parse .{locale}.md and fill ContentDocument.locale. Default to ko when absent.
2. SQLite id: type:slug:locale (e.g. knowledge:webpack-splitchunks:en). List/detail APIs filter with WHERE locale = requested locale.
3. Search index: MiniSearch document ids use the same format as the DB. Filter via SearchScope.locale.
4. Untranslated fallback: On detail, if the requested locale document is missing, redirect to /ko (explicit choice instead of 404 or empty fallback render).
5. Translation metadata: Machine-translated en/ja files set frontmatter translated: machine. Hiding them with status: draft makes that locale's list appear empty.
6. SEO: Sitemap hreflang outputs only locales where a file actually exists. Keep canonical, og:locale, and JSON-LD inLanguage in sync.

Practical application

• Extend build-content-db.ts, schema.ts, loader.ts, queries.ts, and search-index.ts to be locale-aware in one PR.
• Before changing PK/id format, grep all consumers (search hydration, list API, relations).
• Replace copy-pasted redirects in four detail routes with one helper like getLocalizedDocumentOrRedirect.
• Pass the active locale explicitly to relations, load-more, and infinite-scroll APIs.
• When delegating bulk translation, instruct agents: "Never reconstruct body from compressed Read output; re-read with limit pagination."

Trade-offs

When not to use

• When each locale needs a completely different slug and structure (separate content, not translation).
• When you plan to add locale to ids without aligning search and DB consumers first (partial rollout).
• When machine translations are hidden as draft and unintentionally empty that language's catalog.

Common mistakes

• Changing DB id to type:slug:locale but leaving search-index id as type:slug → duplicate throw or zero hydration.
• Scoping list pages to locale but hard-coding relations/load-more to ko.
• Setting translated: machine but hiding with draft status so en/ja nav looks "empty."
• Subagents reconstructing body from compressed Read output so translation files diverge from source.

Related concepts

• json-ld-structured-data — inLanguage and canonical metadata
• inverted-index-full-text-search — search document id consistency
• single-source-of-truth-content-metadata — frontmatter as SSOT