English | 日本語
Kiritan is an internationalization utility that, in addition to the usual "key → string" i18n library scope, also targets document files themselves — Markdown, MDX, and plain text.
You prepare a single "base file" such as README.base.md, and a build operation generates each language's file from it: README.md (default locale) and README.ja.md (other locales), for example.
- Let the translation storage location (split files / inline / catalog) be chosen per use case.
- Allow a machine translation provider (Google Translate, etc.) to be plugged in as an arbitrary translation provider.
- Automatically protect ranges that must never be translated, such as code blocks and links inside Markdown.
- Make output filenames, storage strategy, translation providers, and config file layering all broadly configurable.
- Bundle a minimal runtime i18n (
t(key, params)) as well.
- Advanced grammar such as plurals or ICU MessageFormat (a path is left open as an extension point, but this isn't handled in v1).
- Translation quality management or review workflows themselves (state marking is handled, but a review UI etc. is out of scope).
discover Discover base files by glob
-> parse A Renderer parses the file content
- Plain Markdown/Text: split into the whole document or per paragraph
- If :::kiritan{...} directives (remark-directive) exist, split into blocks per locale/id
-> resolve A TranslationStore fetches each locale's translation
-> interpolate %{name} variable expansion
-> translate(optional) Missing translations are auto-translated via the Translator middleware chain
-> reassemble A Renderer reassembles the final document
-> write Write the output file per the naming template
kiritan build runs this whole sequence. extract / translate / check are separate commands (described later) built on the same foundation.
Build behavior when a translation is missing: with translate.auto: false (the default), if a translation is missing for some locale/segment, build does not error — it falls back to the default locale's (base) original text and writes it, with a marker comment showing it's untranslated (e.g. <!-- kiritan:untranslated (source: en) -->). This means build always succeeds and never produces a broken document. Detecting untranslated content and blocking on it in CI is handled separately by kiritan check (chapter 8).
With future mono-repo-ing in mind (chapter 13), npm workspaces are adopted from v1. The root is a private workspace root, and the actual packages live under packages/*.
packages/
kiritan/ # Core + CLI + built-in stores/renderers. Published to npm as "kiritan"
runtime/ # Minimal runtime i18n (no build-time dependencies). Published to npm as "@kiritan/runtime"
Breakdown of packages/kiritan/src/ (one folder per feature area):
packages/kiritan/src/
index.ts # Public API (defineConfig, build, extract, translate, check)
config/ # Discovery, cascading, and merging (*.kiritanconfig)
discover/ # Discover base files via glob, resolve naming templates
directive/ # Extract :::kiritan{...} via remark-directive
stores/ # sidecar / inline / catalog
renderers/ # markdown / mdx / text
interpolate/ # %{name} expansion (uses @kiritan/runtime's implementation)
translate/ # The middleware chain execution engine (grouping from 7.1)
hash/ # Hashing for stale detection
i18n/ # runtime.sources aggregation, typegen, i18n-key-mismatch detection (chapter 9)
pipeline/ # Orchestration of build/extract/check/typegen
cli/ # citty command definitions
packages/runtime/src/:
packages/runtime/src/
index.ts # createT
interpolate.ts # Shared %{name} implementation (Kiritan core also depends on this)
(i18next-compatible resource loading — centralized in chapter 9.4 — lives in kiritan core's i18n/load.ts, not in @kiritan/runtime, since it's a build-time concern rather than something the runtime itself needs.)
-
Rather than re-exporting
kiritan/runtimefromkiritan,@kiritan/runtimeis its own independent package (kiritanmay depend on@kiritan/runtime, but never the reverse). This lets a project that only wants the runtime avoid pulling inkiritancore (remark and other build-time dependencies) at all. -
Everything except the CLI (
src/cli.ts) keeps full CJS/ESM dual-format support. The remark/unified/micromark ecosystem only ships ESM-only packages (going back to a CJS release would mean "using an older version," which is avoided), sotsdown.config.ts'sdeps.alwaysBundlebundles them directly intodist/index.{cjs,mjs}, eliminating any scenario where a CJS consumer would need torequirean ESM-only package.citty, which is CLI-only, stays an external dependency and isn't bundled. -
Reference implementations of translate middlewares (
@kiritan/deepland@kiritan/google-translate, chapter 13) live in the same workspace underpackages/*. Each is standalone — it doesn't depend onkiritan, since a middleware is just a function whose shape is structurally compatible withtranslate.middlewares. -
extensions/vscode(the VS Code extension, chapter 13) lives outsidepackages/and so is never picked up by the root"workspaces": ["packages/*"]glob — itspackage.json"name"is"kiritan", which would otherwise collide with the CLI package's own name (an npm workspace can't have two packages sharing a name). Its build/test tooling is a root-leveldevDependencyinstead of a package-local one. -
The existing
tsdown/vitest/eslint/ CI (ci.ymland the release workflows) setups need updating for workspace support (per-package build/test/publish). This is treated as an implementation task once the design is finalized. -
Versioning is independent per package (no lockstep, no shared changelog-generation tool). Each package has its own
workflow_dispatchGitHub Actions workflow (release.yml,release-runtime.yml,release-deepl.yml,release-google-translate.yml) — thin wrappers around a shared reusable workflow (_release-package.yml) that does the actual work — so releasing one package can never touch the other by accident:- Trigger
release-<package>from the Actions tab with two inputs:version(a semver bump —patch/minor/major/prerelease— or an explicit version, passed straight tonpm version) anddist_tag(npm dist-tag; empty auto-detects). - The workflow bumps that package's
package.json(no changeset file, no per-package CHANGELOG.md — GitHub's auto-generated release notes from merged PRs are used instead), regenerates everybase/*.base.md-derived doc, and runsnpm publishwith trusted publishing (OIDC — noNPM_TOKENneeded, configured per-package on npmjs.com pointing at that package's own workflow file). - It commits the version bump + regenerated docs, tags the release as
<name>@<version>, pushes, and creates a GitHub Release.
Since
kiritandepends on@kiritan/runtime, bumping runtime's minor/major version doesn't automatically update kiritan's dependency range — that's a deliberate manual follow-up, so that releasing runtime alone never touches kiritan'spackage.json.(An earlier iteration of this design used Changesets, with a changeset file committed per PR driving both the version bump and CHANGELOG generation at release time. It was replaced with the simpler
npm version-based flow above — modeled after oto-lab/npm-biome-ts's single-package release workflow — to remove the per-PR changeset-writing step entirely.) - Trigger
Filenames matching (<mode>|local)?\.?kiritanconfig are recognized (e.g. .kiritanconfig, dev.kiritanconfig, local.kiritanconfig) — deliberately a single, non-extension name rather than .js/.mjs/etc, so file-icon themes (vscode-icons and similar) never mistake it for a generic JavaScript file (chapter 13). Every file is still plain ESM JavaScript under the hood, and is loaded with a lightweight loader, jiti, configured to treat kiritanconfig as a recognized extension (Node's own loader refuses to import() a file whose extension it doesn't know, and kiritanconfig isn't one). Merge order (lower entries take priority, deep-merged):
.kiritanconfig— the base layer. There's no separate "explicit base" alias; a project with no mode/local overrides just has this one file.<mode>.kiritanconfig—modecomes from the--modeflag, or theKIRITAN_MODEenvironment variable otherwise. This layer is skipped if neither is set.local.kiritanconfig— always applied last. Intended to be.gitignored (for local overrides such as API keys).--config <path>/--overlay <path>(repeatable) — additional config files can be layered on from the CLI.
Objects are deep-merged; arrays (such as sources) are replaced by default. Wrap with the mergeArray(...) helper to concatenate instead.
The following is everything configurable via *.kiritanconfig. This is the entirety of KiritanConfig — there are no configuration items beyond it.
| Top-level key | What it configures |
|---|---|
locales |
The list of supported locales and the default locale |
sources |
What documents to build (the TranslationStore strategies in chapter 4, translation in chapter 7) |
naming |
The template/preset for document output filenames (chapter 3.3) |
interpolation |
%{name} variable expansion (chapter 5) |
translate |
Defaults for the translate middleware chain (chapter 7) |
runtime |
Placement strategy for runtime i18n resources (chapter 9) |
check |
What kiritan check treats as a failure condition (chapter 8) |
switcher |
Automatic insertion of language-switcher links (chapter 6.1) |
plugins |
Registration of custom TranslationStore / Renderer implementations |
(ResourceSourceConfig's strategy, custom middlewares passed to translate.middlewares, and custom implementations passed to plugins are all imported directly and passed in from within a *.kiritanconfig file — configuration stays pure "wiring," and the actual implementation is written as an ordinary TS/JS module.)
interface KiritanConfig {
locales: { default: string; list: string[] };
sources: SourceConfig[];
naming?: {
preset?: 'dot' | 'dash' | 'prefix' | 'folder'; // A preset from chapter 3.3. Setting it only swaps out template's default value
template?: string; // Default: "{dir}/{base}.{locale}.{ext}" (takes priority over preset)
defaultTemplate?: string; // A template used only for the default locale (falls back to omitDefaultLocaleSuffix if omitted)
omitDefaultLocaleSuffix?: boolean; // Default: true. Only effective when defaultTemplate is unset
baseSuffix?: string; // Default: ".base" (used to recognize README.base.md)
outputs?: Record<string, string>; // Explicit per-locale output path overrides, e.g. { ja: "i18n/ja/README.md" }
};
interpolation?: {
delimiters?: [string, string]; // Default: ["%{", "}"]
variables?: Record<string, string | Record<string, string>> | ((ctx: BuildContext) => Record<string, string>);
onMissing?: 'error' | 'keep' | 'empty'; // Default: 'error'
skipCodeBlocks?: boolean; // Default: true
};
translate?: {
middlewares?: TranslateMiddleware[]; // Default: [] (equivalent to doing nothing = "manual")
auto?: boolean; // Default: false. Auto-translation of missing translations never runs unless this is true
};
runtime?: {
sources?: ResourceSourceConfig[]; // colocated/split/centralized/embedded may be mixed (chapter 9.1)
fallbackLocale?: string;
};
check?: {
failOn?: Array<'missing' | 'stale' | 'machine' | 'i18n-key-mismatch'>; // Default: ['missing', 'stale', 'i18n-key-mismatch']
};
switcher?: SwitcherConfig; // Enabled by default (chapter 6.1)
markdown?: { alertBlankLineSpaces?: number }; // Trailing spaces on the blank lines inside GitHub alerts. Default: 0 (a bare `>`)
plugins?: {
stores?: Record<string, TranslationStore>;
renderers?: Record<string, Renderer>;
};
}
interface SourceConfig {
glob: string;
strategy: 'sidecar' | 'inline' | 'catalog' | string; // A string means a custom store ID
naming?: KiritanConfig['naming']; // Wholesale-overrides naming for this source only (template/outputs, etc.)
translate?: KiritanConfig['translate']; // Per-source override
switcher?: SwitcherConfig; // Wholesale-overrides switcher for this source only (chapter 6.1)
}Since naming.outputs (per-locale explicit path overrides) tends to need different values per source in practice, it's written on SourceConfig.naming as the primary form (the global naming is kept as just "the template's default").
Since there are several conventions for naming output files (README.ja.md style, README-ja.md style, ja.README.md style, folder-based, etc.), naming.template can be written as any completely free-form string template, while the common forms are available via just a naming.preset value.
| preset | Actual template | Output example (base="README", ext="md", locale="ja") |
|---|---|---|
dot (default) |
{dir}/{base}.{locale}.{ext} |
README.ja.md |
dash |
{dir}/{base}-{locale}.{ext} |
README-ja.md |
prefix |
{dir}/{locale}.{base}.{ext} |
ja.README.md |
folder |
{dir}/{locale}/{base}.{ext} |
ja/README.md |
preset is just a shorthand that swaps template's default value; specifying template directly allows any arrangement or separator not covered by a preset (e.g. {base}_{locale}.{ext}). naming.defaultTemplate, omitDefaultLocaleSuffix, and outputs all work the same way regardless of whether a preset is used.
interface TranslationStore {
id: string;
read(ctx: StoreContext, locale: string): Promise<TranslatedContent | null>;
write?(ctx: StoreContext, locale: string, content: TranslatedContent): Promise<void>;
status(ctx: StoreContext, locale: string): Promise<'missing' | 'partial' | 'complete' | 'stale'>;
}
type TranslatedContent =
| { kind: 'full-text'; text: string; machine?: boolean }
| { kind: 'segments'; segments: Record<string, { text: string; machine?: boolean }> };Strategies can be mixed within the same config (one document using inline, another using catalog, and so on).
For README.base.md, an independent file per language, such as README.ja.md, is prepared, whether by hand or via machine translation. This is closest to how README translations are conventionally handled today. Stale detection is done via a hash comment embedded at the top of the output file (e.g. <!-- kiritan:source-hash: xxxx -->).
This follows remark-directive's standard container-directive syntax (:::name{attrs} ... :::) as-is. No custom line parser is written, so it rides directly on the remark ecosystem (syntax highlighting, existing VS Code extensions, etc.).
Each locale is written as its own, self-contained directive (never a single block with a "switch"-like structure packing multiple cases together).
When targeting the whole document:
:::kiritan{locale=en}
# Kiritan
Internationalization utility for docs.
:::
:::kiritan{locale=ja}
# きりたん
ドキュメント向けの国際化ユーティリティ。
:::When targeting individual sections (wrapping only the parts that differ):
# Kiritan
 <!-- Shared across every locale, not translated -->
:::kiritan{locale=en}
## Usage
This is the usage section.
:::
:::kiritan{locale=ja}
## 使い方
これは使い方セクションです。
:::
## License
Distributed under the WTFPL License. <!-- A shared section just needs to sit outside a directive -->Anything outside a directive is copied as-is into every locale's output as "shared content." This supports translating only part of a document while sharing the rest.
Nesting (using ::: again inside a block): just add more colons on the outer fence, per remark-directive's standard behavior (e.g. using :::note inside ::::kiritan{locale=en}). No special handling is needed on Kiritan's side.
Specifying a locale=xx value not present in locales.list is treated as a typo and errors at build time (it is never silently ignored).
Segment ids are never auto-inferred (position-based or content-hash-based) — the author assigns them explicitly on the base file side. remark-directive's #id attribute shorthand is used as-is.
:::kiritan{#usage-intro}
## Usage
This is the usage section.
:::- The content inside a
:::kiritan{#<id>}block is the base locale's (locales.default) original text itself. - Translations are kept in a separate file, such as
locales/README.ja.yaml, asid → { text, machine, hash }(hashrefers to "what the original text for this id looked like when it was last translated" — it's only used forstaledetection when it no longer matches the current original, never for id matching itself). - Since the author fully controls the id, translations never go "missing" just because the surrounding prose was reworded (the correspondence is pinned by id) — in exchange, assigning and naming ids becomes the author's responsibility (the same mindset as key design in an i18n library).
- The area outside
:::kiritan{#<id>}is treated as "shared content," same asinline. kiritan extractscans the base file's:::kiritan{#<id>}blocks and adds any id not yet registered in the catalog (existing translations are never overwritten). If an id disappears from the base file, it's left in the catalog as an orphan, andkiritan checkwarns about it.
A mechanism for embedding values shared across locales — a version number, a repository URL, a site name, and the like. {{...}} collides too easily with Handlebars/Mustache/i18next and similar, so %{name}, closer to Ruby/Rails' i18n, is the default (the delimiters themselves can be changed via interpolation.delimiters).
Current version: %{version}interpolation: {
variables: {
version: '1.2.0',
siteName: { en: 'Kiritan', ja: 'きりたん' }, // Per-locale override
},
}- A variable's value comes from
interpolation.variables(or avariablesfunction's return value) alone — a catalog translation record, for instance, never supplies a variable's value. If both a per-locale value ({ en: ..., ja: ... }) and a shared value are defined for the same variable name, the per-locale value takes priority, falling back to the shared value if absent. - Can be escaped with a backslash, as in
\%{literal}. - With
interpolation.skipCodeBlocks: true(the default), expansion is skipped inside code blocks / inline code. - How an undefined variable is handled is controlled by
onMissing(default'error'), so a typo can be caught at build time. - Making the variable resolution itself a function also allows dynamic values, such as reading a value out of
package.json.
interface Renderer {
id: string;
extensions?: string[]; // Claimed by extension when a source has no explicit `renderer` (lowercase, with the dot)
strategies: StoreStrategy[]; // Which of sidecar/inline/catalog this format supports
supportsDirectives?: boolean; // Default true. false = no `:::kiritan{...}` and no switcher
parse(sourceText: string): Root; // mdast tree, the same shape every pipeline stage operates on
stringify(tree: Root): string;
comment?(text: string): string; // How to write an invisible comment; absent = no hash/untranslated markers
}markdown: AST parsing via remark +remark-directive. Code blocks, inline code, and link URLs are protected, and:::kiritan{...}directives are also split apart here. A leading---YAML front-matter block is kept as one opaque node (viaremark-frontmatter), so it is never translated, interpolated, or reformatted — it passes through every build verbatim. That means asidecartranslation carries its own front matter (translate it by hand or via a middleware), whileinline/catalogbuilds repeat the base file's front matter unchanged in every locale.- Renderers are resolved per source file: an explicit
SourceConfig.rendererid wins, then an extension match (aplugins.renderersentry beats a built-in claiming the same extension), thenmarkdown— so a file with an unfamiliar extension is still processed as Markdown, as it always was. The renderer'sstrategieslist is checked against the source's built-instrategyup front, and an unsupported combination (e.g.inlineon a format that only declaressidecar) is rejected with a clear error before anything is built. A customplugins.storesstrategy name isn't checked against the list, since a store's own registration is what validates it.textandmdxare built in. text(.txt/.text): the whole file is one text node, so it's written back byte for byte — nothing is reflowed, escaped, or normalized — apart from%{name}interpolation. With no Markdown syntax there's nowhere for a:::kiritan{...}directive or a switcher link, so it supports onlysidecar(supportsDirectives: false), and it has no comment syntax, so it gets nokiritan:hashmarker and no stale detection:kiritan checkreports a missing translation but never a stale one, andkiritan translatefills in only what's missing. It deliberately isn't split into paragraphs — that split would only matter for a per-segment strategy, which plain text can't offer.mdx(.mdx): Markdown plus JSX,import/export, and{expressions}, viaremark-mdxlayered under the same directive and front-matter handling asmarkdown. JSX, ESM, and expressions each parse into their own mdast node that the pipeline never treats as prose, so they pass through untouched, and:::kiritan{...}works exactly as in Markdown with all three strategies. Two differences from Markdown follow from MDX's own syntax.%{name}interpolation doesn't apply: the{opens a JS expression, sonamenever reaches the pipeline as text (it round-trips unchanged; use MDX's own{expression}for values instead). And thekiritan:hash/kiritan:untranslatedmarkers are written as a JS block comment inside an expression, since an HTML comment is a syntax error in MDX.
Builds a language-switcher link automatically at build time, of the kind commonly seen in bilingual READMEs: [English](README.md) | [日本語](README.ja.md). Since this is mechanical link generation, a different kind of thing from translation, it's enabled by default, unlike translate.auto (off by default).
Specifying where it's inserted: writing ::kiritan{switcher} — a remark-directive leaf directive (a content-less ::name form) — anywhere in the base file inserts it at that spot (the same remark-directive mechanism as the container directives in chapters 4.2/4.3).
# Kiritan
::kiritan{switcher}
Kiritan の説明...If no explicit marker exists, it's auto-inserted at switcher.position (default 'after-heading': right after the first heading, or at the top if there's none) when switcher.enabled (default true). If a marker exists, it's always used regardless of the enabled/position values (an explicit placement wins over the default behavior).
Generated content: for each locale in locales.list, a link to that locale's output file path (reusing the naming resolution from chapter 3.3, also honoring a per-source naming.outputs override) is automatically computed as a path relative to the output file currently being built, then joined with a separator (default " | "). There's no way to specify an href manually (if you want to write a link by hand, just write it yourself instead of using this feature). The current locale itself isn't linked — it's shown in bold (it can also be turned into a link via currentLocaleLink: true).
Displayed language labels: Kiritan doesn't maintain its own list of language names (a hand-maintained list risks gaps). The default label uses the standard Intl.DisplayNames (ECMA-402, built into Node.js, based on CLDR data) to automatically display each locale's autonym — the name a locale uses for itself in its own language (e.g. "日本語" for ja, "English" for en). This needs no extra dependency and no list to maintain.
// Default label resolution (used for any locale with no explicit override in labels)
new Intl.DisplayNames([locale], { type: "language" }).of(locale);switcher.labels remains as an opt-in override for cases where this default needs to be replaced (wanting a different name, a custom locale code Intl.DisplayNames doesn't know, excluding an unsupported locale from the list, etc.).
interface SwitcherConfig {
enabled?: boolean; // Default: true (only controls automatic insertion when no marker exists; a marker is always honored)
position?: 'top' | 'after-heading' | 'none'; // Default: 'after-heading'
separator?: string; // Default: " | "
/**
* Per-locale display label overrides. Any unspecified locale uses its
* Intl.DisplayNames autonym as its label (falling back to the locale
* code itself if that fails). A value of `false` excludes that locale
* from the switcher entirely (e.g. a locale still in draft, or one
* whose custom locale code Intl.DisplayNames doesn't recognize).
*/
labels?: Record<string, string | false>;
currentLocaleLink?: boolean; // Default: false
render?: (ctx: SwitcherRenderContext) => string; // Fully overrides how the whole line is rendered
}
interface SwitcherLink {
locale: string;
label: string;
href: string; // A relative path, always computed automatically
isCurrent: boolean;
}
interface SwitcherRenderContext {
locale: string; // The locale currently being built
links: SwitcherLink[]; // In locales.list order (a locale set to false in labels is excluded)
}switcher: {
labels: { en: 'English', ja: '日本語', es: false }, // es is excluded from the switcher
}It can be wholesale-overridden per source via SourceConfig.switcher (disabling it for a specific document, changing its labels, etc.).
Generated example (locales.list: ['en', 'ja', 'es'], the labels above, building en):
**English** | [日本語](README.ja.md)Since ::kiritan{switcher} inserts the same content into every locale's output, it should be placed outside an inline/catalog strategy's :::kiritan{locale=...}/:::kiritan{#<id>} block (in the shared-content area). Placing it inside a block leads to the confusing behavior of the switcher appearing only in that one locale's output, so a warning is issued at build time in that case.
Rather than picking a single provider, this is designed so small pieces of processing can be chained together, Vite/Koa-plugin style. For one missing translation, middlewares are applied in order from the front, and processing stops as soon as one of them resolves a value.
interface TranslateContext {
text: string; // The text to translate (the base side's original)
from: string; // e.g. "en"
to: string; // e.g. "ja"
source: SourceConfig; // Which source this translation is for
segmentId?: string; // catalog strategy only: the <id> of :::kiritan{#<id>}
// (used for cache keys or glossary lookups; omitted for sidecar/inline)
}
// Single form (the simplest — called once per item)
type TranslateMiddleware = (
ctx: TranslateContext,
next: () => Promise<string | null>
) => Promise<string | null>; // Returning null / not calling next() = delegate to the next middleware
// Batch form (for batching multiple items into one API call — marked with `batch: true` to distinguish it)
type BatchTranslateMiddleware = {
batch: true;
handle: (
ctxs: TranslateContext[],
next: () => Promise<(string | null)[]>
) => Promise<(string | null)[]>;
};translate: {
auto: true,
middlewares: [
cacheMiddleware({ dir: '.kiritan/cache' }), // Return an existing cached translation if there is one
googleTranslate({ apiKey: process.env.GOOGLE_API_KEY }), // Otherwise, hit the API
postProcess((text) => text.trim()), // Clean up the result before finalizing it
],
}- The default is
middlewares: [](equivalent tomanual), and auto-translation never runs at all unlesstranslate.autoistrue. This default (off) is kept as the design evolves, and is re-confirmed whenever a new place that needs an on/off decision comes up. - The calling convention (once per paragraph, or all at once as a batch) isn't decided by the core — middleware authors are free to implement it either way. Two forms are allowed for this reason:
- Single form:
(ctx: TranslateContext, next) => Promise<string | null>— the simplest form, called once per item. - Batch form:
(ctxs: TranslateContext[]) => Promise<(string | null)[]>— for when multiple items should be processed together in one call. The core looks at a middleware's shape (its function signature/flag) and passes items one at a time for a single-form middleware, or all missing items together for a batch-form one. - Kiritan itself doesn't bundle concrete provider middlewares (to avoid adding dependencies). They ship as separate packages instead, starting with
@kiritan/deepland@kiritan/google-translate(chapter 13).
- Single form:
- Anywhere auto-translation fills a gap, it's always marked
machine: true(a field forcatalog, a comment marker forsidecar/inline), sokiritan checkcan detect it as awaiting review. - The whole chain can be wholesale-overridden per source (
sources[i].translate).
Official reference implementations are split out as separate packages, such as
@kiritan/deepland@kiritan/google-translate(see chapter 13).
Single-form and batch-form middlewares may be mixed within the translate.middlewares array. The pipeline scans the array from the front, automatically grouping consecutive single-form middlewares into one "single group," while each batch-form middleware forms its own standalone "batch group."
middlewares: [
cacheMiddleware(), // Single form ┐
localGlossary(), // Single form ┘→ Group A (chained item-by-item via ctx/next)
googleTranslateBatch(), // Batch form → Group B (all items still missing at that point, passed together)
postProcess(), // Single form → Group C (applied only to what Group B didn't resolve)
]Groups run in array order, and only the items a group didn't resolve are passed on to the next group. This lets a combination like "check the cache one item at a time first → throw the rest at an API together → format each remaining item one at a time at the end" be expressed naturally.
-
sidecar/inline: embed a hash comment of the source into the output (or each block), and compare it against the base side's current hash. -
catalog: each segment's translation record keeps the corresponding base hash. -
kiritan checkdetects the presence ofmissing/stale/ unreviewedmachinetranslations and runtime resourcei18n-key-mismatch(chapter 9.4), and can exit non-zero in CI. What's checked is configurable:check?: { failOn?: Array<'missing' | 'stale' | 'machine' | 'i18n-key-mismatch'>; // Default: ['missing', 'stale', 'i18n-key-mismatch'] (machine is a warning-only default) };
-
kiritan check --jsonprints the sameCheckResultas structured JSON instead (plusinterpolationVariableNamesanddelimiters, resolved frominterpolation) — meant for editor tooling rather than humans; the VS Code extension's inlinemissing/stale/machineindicators and undefined-%{name}warnings (chapter 13) are its only consumer so far. -
Since the hash function only needs to be good enough for tamper detection and doesn't need cryptographic strength, a lightweight non-cryptographic xxhash-family hash (e.g.
xxhash-wasm) is adopted as a dependency. The output is embedded as a hex string in the hash comment/catalog file.Implementation note: this was ultimately implemented via Node's built-in
node:cryptoinstead, to avoid a WASM dependency's bundling complexity in a package that ships both CJS and ESM — seepackages/kiritan/src/hash/index.ts.
The classic i18next approach of "aggregate every key into locales/{lang}.json" has persistent complaints: the file bloats, unused keys go unnoticed, PR diffs become hard to read, and comparing all languages for a given key is awkward. Kiritan doesn't take this as its only assumption — following the same thinking as the document-side TranslationStore (chapter 4), it lets the resource's location be chosen as a strategy.
interface ResourceSourceConfig {
glob: string;
strategy: 'colocated' | 'split' | 'centralized' | 'embedded' | string; // A string means a custom strategy ID
exportName?: string; // The named export read for the 'embedded' strategy. Default: "i18n"
namespace?: (filePath: string) => string; // Default: auto-derived from the file path
}| strategy | Placement | Example |
|---|---|---|
colocated |
One file next to the component, holding every locale | Button.i18n.ts |
split |
Also next to the component, but one file per locale | Button.en.i18n.ts / Button.ja.i18n.ts |
centralized |
Gathered into a dedicated directory, per locale (or as one file). Also an i18next-compatible input format | locales/en.json / locales/{locale}/common.json |
embedded |
No dedicated file — written directly inside the component's own file | export const i18n = {...} inside Button.tsx |
Every strategy is ultimately converted into the same internal shape, ResourceModule (key → { locale: value }), so createT, kiritan typegen, and the key-mismatch check in chapter 9.6 all work identically regardless of strategy. Multiple strategies may be mixed within the same project (by listing multiple entries in runtime.sources).
runtime: {
sources: [
{ glob: 'src/**/*.i18n.{js,ts}', strategy: 'colocated' }, // The default recommended form
{ glob: 'src/**/legacy/**/*.i18n.{en,ja}.ts', strategy: 'split' },
{ glob: 'locales/{locale}/*.json', strategy: 'centralized' },
{ glob: 'src/**/*.tsx', strategy: 'embedded', exportName: 'i18n' },
],
fallbackLocale: 'en',
}The default config kiritan init generates recommends the colocated strategy with src/**/*.i18n.{js,ts} (.json may also be included) as the default. It doesn't assume .ts — it's usable as-is in a JS-only project too.
// src/components/Button/Button.i18n.ts
export default {
submit: { en: 'Submit', ja: '送信' },
cancel: { en: 'Cancel', ja: 'キャンセル' },
};import messages from './Button.i18n';
const { t } = createT(messages);
t('submit'); // Resolved based on the current localetype LocaleMap = Record<string, string>; // { en: 'Submit', ja: '送信' }
type ResourceModule = Record<string, LocaleMap>; // { submit: {...}, cancel: {...} }
function createT<R extends ResourceModule>(
resources: R,
opts?: { locale?: string; fallbackLocale?: string }
): {
t<K extends keyof R & string>(key: K, params?: Record<string, string | number>): string;
locale: string;
setLocale(locale: string): void;
};- The recommended default is
*.i18n.ts(getting the most benefit from type safety), but*.i18n.js(for JS projects) and*.i18n.jsonare supported equally. - Type safety comes for free: since the
messagespassed tocreateT(messages)is just a plain TS object (.i18n.ts) or JSON viaresolveJsonModule(.i18n.json), TypeScript's generic inference alone narrowst()'s first argument down to a real key. A typo becomes a compile error with no extra code generation needed (chapter 9.6 covers aggregating multiple files). For.js, the benefit of inference is limited unless JSDoc type annotations are present (partially effective in acheckJsenvironment). - A gap between locales is visible at a glance, within the same file: forgetting to write
jaas insubmit: { en: 'Submit' }doesn't require searching across files, i18next-style — it's noticed right there (mechanical detection is covered in chapter 9.7). - Simple
%{param}interpolation (sharing the same notation and implementation as the document-side variable expansion). - The fallback order is
locale → fallbackLocale → the key itself. - Plurals and ICU are out of scope for v1. Left extensible later via a
formattersoption. - Since a component's
.i18n.tsdisappears along with the component itself when it's deleted, the "unused translation keys linger forever" problem common with i18next's centralized management is much less likely to happen here. From a bundler's perspective too, an unused component's translations aren't dragged in (this matches the unit of code splitting).
src/components/Button/
Button.en.i18n.ts // export default { submit: 'Submit', cancel: 'Cancel' }
Button.ja.i18n.ts // export default { submit: '送信', cancel: 'キャンセル' }
Files matching a glob that includes a locale token (e.g. extracting the {locale} part from an actual filename matching *.{locale}.i18n.ts) are bundled together as one set and internally merged into the same ResourceModule as 9.2. This is an option for when you want to stay colocated but avoid one file growing long with every language in it. Unlike 9.2, the benefit of "noticing a gap within the same file" is lost, so gap detection relies on the mechanical check in chapter 9.7.
To ease migration to and from i18next, its convention (per-locale centralized files like locales/{locale}/{namespace}.json) is supported as-is as an input format. Once loaded, the content is internally converted into a ResourceModule before being passed to createT/typegen.
- i18next's plural suffixes (
key_one/key_other, etc.) are kept and passed through as values, but not interpreted (sincet()has no plural-selection logic in v1, the caller has to explicitly pick the right key). - The namespace follows i18next's own file layout (
{namespace}.json) as-is.
For when you don't even want a dedicated translation file — you want to write it directly into the component's implementation file.
// src/components/Button/Button.tsx
export const i18n = {
submit: { en: 'Submit', ja: '送信' },
cancel: { en: 'Cancel', ja: 'キャンセル' },
};
export function Button() {
const { t } = createT(i18n);
return <button>{t('submit')}</button>;
}- If you're just calling
createT(i18n)directly within the app, no involvement from Kiritan is needed (same as 9.2, it's just a plain TS object). - Registering
strategy: 'embedded'inruntime.sourcesmakeskiritan typegen/kiritan checkread that file at build time (the same jiti-based dynamic import as reading a config file's.ts), pull out just the named export specified byexportName(default"i18n"), and include it for aggregation/checking. - Since the component's logic and its translations live in the same file, the file count doesn't grow, but there's a trade-off: files tend to get larger, and importing a large number of
embeddedfiles raises import cost.
Importing a single file directly (9.2/9.5) gets type safety from TS inference alone, but when runtime.sources aggregates multiple files into one shared t() (e.g. wanting one common t() across the whole app), there's no longer a way to statically know the shape of the aggregated result. kiritan typegen exists for exactly this case.
- The namespace is auto-derived from the file path (e.g.
src/components/Button/Button.i18n.ts→components/Button). No manual namespace management is needed (it can be overridden via anamespacefunction). kiritan typegengenerates a.d.tsfrom the aggregated resource's shape (namespace × key × locale), bringing calls liket('components/Button.submit')after aggregation under type checking too.- The generated type information also feeds into the cross-locale key-mismatch check in chapter 9.7.
Adds an item to kiritan check (chapter 8) that detects cross-locale key mismatches in runtime resources (a key missing from, or extra in, only one locale).
colocated/embedded(every locale in one file) can spot a gap just by statically looking at a single file (no cross-file matching needed).split/centralized(one file per locale) requires matching up the key sets of the corresponding files to detect a mismatch.- Via
check.failOn's'i18n-key-mismatch', it can be wired into CI the same way as the document-sidemissing/stale.
The CLI's skeleton uses citty (subcommand definitions, help output, and typed args aren't hand-rolled). --lang localizes what Kiritan itself says: command and option descriptions, and each command's output lines (packages/kiritan/src/cli/messages.i18n.ts). citty's own help labels (USAGE, OPTIONS, COMMANDS) and argument errors stay in English. That boilerplate reads the same in any CLI, so translating it isn't worth replacing citty's renderer. kiritan used yargs for a while for its bundled translations of that boilerplate. It moved back to citty in 0.7.0 because yargs 18 needs Node.js ^20.19.0 || ^22.12.0 || >=23, while citty has no dependencies and runs on Node.js 18.3+. citty accepts any argument, so each command also rejects arguments it doesn't declare (Unknown argument: --locle), the way yargs's .strict() did.
kiritan init [--lang] [--force] # Scaffolds .kiritanconfig / base/README.base.md / a .gitignore entry for local.kiritanconfig
kiritan build [--lang] [--mode] [--config] [--locale] # Runs the full pipeline (every strategy)
kiritan extract [--lang] [--mode] [--config] [--locale] # catalog-strategy sources only. Creates/updates catalogs
kiritan translate [--lang] [--mode] [--config] [--locale] # Fills missing/stale via translate.middlewares (every strategy)
kiritan typegen [--lang] [--mode] [--config] # Generates a .d.ts from the runtime.sources aggregation (chapter 9.6)
kiritan check [--lang] [--mode] [--config] [--locale] [--json] # For CI (or editor tooling with --json). Exits non-zero on missing/stale/unreviewed/i18n-key-mismatch
kiritan verify [--lang] [--mode] [--config] [--locale] [--json] # Checks generated docs are byte-for-byte what build would write (by hash); writes nothing. Exits non-zero on a mismatch/missing file
kiritan init leaves every file it would write alone if it already exists (--force overwrites) — safe to run again in a project that already has some of the three set up. build/check/translate/extract all accept --locale <locale> to restrict a run to one locale instead of every locale in locales.list; kiritan typegen doesn't, since it always aggregates every locale into one runtime module.
--lang <en|ja> picks the CLI's own display language — every command/option description, --help output, and the CLI's own plain-text success/no-op lines (not --json output, which stays machine-readable regardless) — as opposed to --locale, which picks which document locale a run acts on. Without --lang, it falls back to KIRITAN_LANG, then the usual POSIX locale env vars (LC_ALL, LC_MESSAGES, LANG), then en; an explicit but unsupported --lang (e.g. --lang fr) is reported back as a normal invalid-choice error rather than silently falling back. The CLI's own strings live in packages/kiritan/src/cli/messages.i18n.ts — a colocated-strategy runtime.sources resource in this repo's own .kiritanconfig, so kiritan check/kiritan typegen catch a missing en/ja pair here the same way they would for any other project's own resources. A CheckIssue.detail or a thrown Error.message from a pipeline function (packages/kiritan/src/pipeline/*.ts) is never translated, though — those are library-level strings used by both the CLI and the programmatic API, and stay in English the same way any Node library's own exceptions would, regardless of --lang.
export { defineConfig, build } from 'kiritan';
export type { KiritanConfig, TranslationStore, Renderer, TranslateMiddleware, BatchTranslateMiddleware } from 'kiritan';The runtime portion is provided as the independent package @kiritan/runtime (chapter 2.1) rather than a subpath of kiritan, so that document-build-related code (remark, etc.) never has to be bundled in at all.
export { createT } from '@kiritan/runtime';
export type { CreateTOptions } from '@kiritan/runtime';| Kind | Status in v1 |
|---|---|
| Translation storage strategy | sidecar / inline / catalog are built in and hardcoded, but a source using any other strategy string is now genuinely dispatched through plugins.stores[strategy] if one is registered there (chapter 4, TranslationStore) — build/check/translate/extract all call into it. A strategy matching neither a built-in nor a registered store throws a clear error, in all four commands. |
| Runtime resource placement strategy | colocated / split / centralized / embedded (chapter 9.1) are genuinely dispatched via ResourceSourceConfig.strategy. A custom string strategy is accepted by the type but not handled by anything yet. |
| Translate middleware | Genuinely extensible today: no built-in providers, wired entirely through the translate.middlewares array (users implement freely; examples are provided in docs/). |
| File renderer | Genuinely extensible today via plugins.renderers (chapter 6): a renderer is a parse/stringify pair over the same mdast tree every pipeline stage uses. markdown, text, and mdx are built in. |
| Language-switcher rendering | Genuinely extensible today via SwitcherConfig.render (chapter 6.1). |
plugins.stores and plugins.renderers are both wired as of chapter 13.
None at this time. Anything that comes up during implementation will be appended here.
translate.autois enforced: done. Chapter 7 always said auto-translation never runs unlesstranslate.autoistrue, but the implementation ignored the flag and ran any configured middleware.kiritan translatenow runs nothing unless the effectivetranslateconfig hasauto: true, and when a source has middlewares butautois off it says so (TranslateResult.autoDisabled, printed in the CLI) rather than silently doing nothing. A source's owntranslatereplaces the top-level one entirely (asSourceConfig.translatealways documented), so it does not inheritauto: it needs its ownauto: true. Every README example now sets it.machinemarkers and stale detection forsidecarandinline: done. Chapter 7 always said auto-translated content is markedmachine("a field forcatalog, a comment marker forsidecar/inline"), but onlycatalogwas. Nowkiritan translatewrites akiritan:machinecomment line under asidecartranslation's hash marker, andkiritan checkreportsmachineuntil a reviewer deletes it (a renderer with no comment syntax, i.e.text, gets no marker and so no review flag, as it never had a hash).inlinegained the rest:kiritan translateused to throw for it, since a translation has no file of its own. It now writes into the base file, by source offset so nothing else is reformatted: locale blocks written next to each other (nothing else between them) form a group, a locale missing from a group gets a block after it, and a block that carries ahashis rewritten when the default-locale block it came from has changed. A written block is:::kiritan{locale=ja machine hash=<hash of the source block>}(the same number of colons as its source, so nested directives still work):machineis the review flag, andcheckreports ahashmismatch asstale. A block with nohashwas written by hand and is never touched or flagged.buildignores both attributes.markdown.alertBlankLineSpaces: done. The serializer writes the blank line inside a GitHub alert as a bare>, which can't satisfy a house style that wants>plus trailing spaces (this repo's own is exactly three). The option pads those lines after the fact, only inside alert blocks and never inside a fenced code block within one. It defaults to 0 (a bare>); this repo sets it to 3, so its generated READMEs now match the style of their sources.- Dependency policy (ESM/CJS): decided. Anything a consumer loads through a package's API must be a library whose latest release is ESM/CJS-dual (see CONTRIBUTING); the CLI may use ESM-only ones. Audited across the repo:
@kiritan/middleware, the provider packages and@kiritan/runtimecomply (@lezer/markdown,es-toolkit,limiter,html-entities,ofetch;jitiandtinyglobbyinkiritan). The exception iskiritan'sunified/remark-*stack, which is ESM-only and whose stringifier has no dual-format replacement; it stays, bundled intodist/, so CJS consumers are unaffected. Replacing it would mean rewriting the directive/interpolation/switcher pipeline as source-range edits on@lezer/markdown's positions and finding a different way to support.mdx(remark-mdxhas no substitute), and would change how generated documents are formatted; that is left for when it is worth doing. The rest of the code was checked for hand-written logic a library could replace:deepMerge(config layering) was left alone, sincedefu's array and null semantics differ from themergeArraycontract and the saving is a few lines. - Official translate-middleware packages:
@kiritan/deeplis done —deepl()(one request per item) anddeeplBatch()(one request per language pair, up to DeepL's 50 texts).%{name}placeholders are wrapped in a tag DeepL is told to ignore (tag_handling: xmlwithignore_tags), which is also why the rest of the text is XML-escaped on the way in and un-escaped on the way out. The request shape is unit-tested against DeepL's documented API with a fakefetch, but has not been run against the live service.@kiritan/google-translateis done too, on the same footing:googleTranslate()/googleTranslateBatch()against the Cloud Translation Basic (v2) API, chunked at 128 strings / 30k code points per request. It keeps%{name}intact with<span translate="no">andformat: "html", so it HTML-escapes the rest on the way in and decodes the entities Google adds on its own (an apostrophe comes back as') on the way out. Likewise unit-tested against the documented shape only, not the live API. @kiritan/middleware(packages/middleware): done.createTranslator({ name, translate | translateBatch, ... })turns a bare "translate this text" function into a complete batch-form middleware, so a provider (or a user's own code) only writes the call itself. It exists because a middleware receives raw Markdown — a whole file forsidecar, one directive body forcatalog— and a bare provider call mishandles that: it translates code, URLs, front matter and:::kiritanlines, and a long README exceeds the provider's length limit. The layer (1) swaps protected spans for[[N]]tokens and refuses a result that lost one (the token shape was picked by testing against Google's and MyMemory's real endpoints, which rewrote<span translate="no">and splitXPH0X-style words); (2) splits a text overmaxCharsat paragraph boundaries and rejoins it with the original spacing, and packs short ones intotranslateBatchcalls undermaxBatchSize/maxBatchChars; (3) applies concurrency, request spacing and retries (network errors and 408/409/425/429/5xx only); (4) caches finished translations, in memory or in a JSON file; (5) withonError: "skip"leaves only failing texts to the next middleware. The Markdown is parsed with@lezer/markdown(GFM included) instead of matched with patterns: every non-prose range the parser reports is shielded, so structure such as tables, nested fences, setext headings, reference links and HTML blocks is handled by the parser rather than by a regex list that would have to track Markdown. Retries and concurrency usees-toolkit, request spacinglimiter, sentence/word/grapheme cutsIntl.Segmenter, and locale parsingIntl.Locale. It has no dependency onkiritan(structural types).@kiritan/deepland@kiritan/google-translateare built on it too: the layer'swireoption lets each wrap the[[N]]tokens in its provider's own "leave this alone" markup (DeepL's ignored XML tag, Google'stranslate="no"span) while the layer does the protecting, splitting and retrying. Their size limits are measured on the text as actually sent (escaped, wrapped and, for DeepL, JSON-encoded), so a whole README sent for asidecartranslation is split rather than rejected.@kiritan/free-translate(packages/free-translate): done. Middlewares that need no API key, all built on@kiritan/middleware. Hosted:myMemory()(documented free API, 500 bytes per request, so it uses the layer'smeasureoption to split by bytes) andgoogleFree()(the unofficialclients5.google.comdict-chrome-exendpoint; batched; validates language codes because the endpoint returns the source text unchanged for an unknown one). Self-hosted:libreTranslate({ baseUrl })(the open-source engine on a server you run; arrayq, so batched) andappsScript({ url, secret })(a small Google Apps Script web app you deploy from your own account, using the built-inLanguageApp.translate; the README carries the script to paste in, with the deployment steps and the two ways it usually goes wrong: not deployed for "Anyone", or edited without a new version). Apps Script answers a POST with a 302 to a one-off result URL, so the provider is tested against a real local HTTP server that answers that way, not only a fakefetch. Which hosted providers to build was decided by trying them from a real machine: MyMemory and the Chrome-extension endpoint worked, while the plainclient=gtxendpoint hit a CAPTCHA, Lingva sat behind Cloudflare, Microsoft Edge's translate auth returned nothing, and libretranslate.com requires a key. An Apertium provider (public server, European languages only, no Japanese) was built and then removed as useless for the languages most Kiritan projects need.googleFree,myMemoryand the layer were run end to end against the live services on a Markdown sample (front matter, heading, bold, list, quote, table, code fence, an entity,%{name}).libreTranslateandappsScriptare verified against their documented request/response shapes only: no LibreTranslate server or Apps Script deployment was available to run them against.googleFreeis unofficial and may be throttled, blocked or change; the README says so.- AI Agent Skill:
skills/kiritan— done. ASKILL.md(no npm package, no build step) teaching a coding agent the directive syntax, which CLI command to reach for, and common mistakes to avoid, with thecatalog/sidecarstrategies, runtime i18n, and config detail split intoreferences/files that are read only when a task calls for them (progressive disclosure, per the Agent Skills specification). See skills/README.md for installation. kiritan init: done. Scaffolds.kiritanconfig,base/README.base.md, and a.gitignoreentry forlocal.kiritanconfigin a fresh project — the generated config pointssourcesatbase/README.base.mdwithnaming.templateoverridden to strip{dir}(soREADME.md/README.ja.mdland at the project root rather than insidebase/, matching the convention this repo's own.kiritanconfiguses) and aruntime.sourcesentry recommending thecolocatedstrategy (chapter 9.1). Every file is left alone if it already exists unless--forceis passed, so running it again in a partially-set-up project is safe.- A per-command
--localeflag: done, forbuild/check/translate/extract— each accepts--locale <locale>to restrict a run to one locale instead of every locale inlocales.list, via a sharedresolveTargetLocaleshelper that also rejects a locale not inlocales.listwith a clear error.build's switcher links still cover every configured locale regardless of--locale, since the other locales' files already exist on disk and the switcher isn't only describing the current run.kiritan typegendoesn't support it — it always aggregates every locale into one runtime module, so there's no meaningful way to restrict it to one. - VS Code extension:
extensions/vscode— done. Syntax highlighting for:::kiritan{...}/::kiritan{...}blocks (a declarative TextMate grammar injected into Markdown, no compiled extension code) is done. Published asotoneko1102.kiritan(a VS Code extension identifier can't contain a/, ruling out@kiritan/vscodeas originally envisioned; itspackage.json"name"is the plain"kiritan"). Since that collides with the CLI package's own npm name, it lives underextensions/rather thanpackages/and so is never picked up by the root"workspaces": ["packages/*"]glob — its build/test tooling lives in the rootpackage.json'sdevDependenciesinstead (chapter 2.1). Highlighting for%{name}(and its\%{name}escape), folding for:::kiritanblocks (colon-count matched via a small stack, so nesting other directives around a kiritan block doesn't confuse it), jump-to-definition from:::kiritan{#<id>}to its entry in the sibling<base>.<locale>.catalog.json, undefined-%{name}-variable warnings, and inlinemissing/stale/machineindicators are all done — the last two settled the "bigger design question" the others were left waiting on: rather than requiringkiritan's internals in-process (real crash/version-skew risk from a broken or mismatched project install),diagnostics.cjsspawns the workspace's own locally-installedkiritan check --jsonas a child process, the same approach ESLint/Prettier's editor integrations use for their own local installs.npx --no-installmeans a project that doesn't depend onkiritanat all is silently skipped rather than triggering a surprise network install.kiritan checkgained a--jsonflag andCheckIssue.id(the catalog segment id, when there is one) specifically to support this.%{name}uses inside a fenced code block or inline code span are never flagged, matchinginterpolation.skipCodeBlocks's own default — caught by testing this against the extension's own README, which shows the syntax as a literal example. Only the default%{/}delimiters are supported for the undefined-variable check; a project with custominterpolation.delimitersstill gets everything else. It also registers*.kiritanconfigas its own language, delegating highlighting tosource.jsvia a TextMateincludeand reusing JavaScript's bracket/comment/indent rules via its ownlanguage-configuration.json— this is why config files are named*.kiritanconfigrather than.kiritan.mjs(chapter 3.1): a file icon theme's own rules always beat a language's fallback icon, so keeping a real.mjsextension would have permanently shown a generic JavaScript icon in themes like vscode-icons. No icon theme has a rule for a filename it's never heard of, so registering the language here is enough to get a Kiritan-branded icon everywhere, with no per-theme configuration needed. Real code completion needed more than a grammar, though — the built-in TypeScript/JavaScript language service only activates for the actualjavascript/typescriptlanguage ids, and giving*.kiritanconfigthe realjavascriptid would let vscode-icons' own language-based icon rule override the custom one.extension.cjsbridges this: it mirrors a*.kiritanconfigdocument's content into an in-memoryjavascriptdocument (aTextDocumentContentProvider-backed virtual document, not an untitled one — an untitled document is a real editable buffer that VS Code counts as unsaved, which an earlier version of this bridge did by mistake) and forwards completion requests to VS Code's own built-in provider for it, so the icon and full IntelliSense both hold at once. - Vim/Neovim plugin:
extensions/vim— done, at parity with the VS Code extension (Neovim-only for the last two, which needvim.diagnostic/vim.system). Ended up as plain Vimscript rather than the shared tree-sitter grammar or LSP originally envisioned here, since that's a real upfront investment and the immediate need (matching the VS Code extension's own v1) didn't call for it yet:after/syntax/markdown.vimhighlights:::kiritan{...}/::kiritan{...}directives and%{name}interpolation by layering onto the built-inmarkdownsyntax, the Vimscript equivalent of the VS Code extension's TextMate grammar injection, andftdetect/kiritanconfig.vimassigns the realjavascriptfiletype to*.kiritanconfigfiles directly — no need for VS Code'skiritanconfig-language workaround, since Vim/Neovim's icon ecosystem doesn't force the same vscode-icons-language-rule tradeoff (chapter 3.1). Verified against a real headlessvim -u NONEprocess (synID()/synIDattr()at specific positions), not just asserted against the.vimsource, the same rigor the VS Code extension's grammar tests use — this actually caught a real gotcha along the way: Vim's:syntax onautocommand only ever runsruntime! syntax/<ft>.vimagainst each'runtimepath'entry's ownsyntax/subdirectory, never a nestedafter/syntax/, so a plugin'safter/subdirectory has to be added to'runtimepath'as its own separate entry (which plugin managers do automatically) forafter/syntax/markdown.vimto load at all. Folding (after/ftplugin/markdown.vimsets'foldexpr'toautoload/kiritan.vim'skiritan#FoldExpr, precomputing every line's fold level with the same colon-count-stack algorithm asfolding-core.cjs, cached per buffer againstb:changedtick) and jump-to-catalog-entry (:KiritanJumpToCatalog, bound to nothing by default — see the plugin's README for wiring up<Plug>(kiritan-jump-to-catalog); populates the quickfix list when more than one locale's catalog matches) are done too, verified the same real-vim-process way. Undefined-%{name}detection and inlinemissing/stale/machineindicators are done too, but Neovim-only (nvim-0.10+) —lua/kiritan/diagnostics.lua, auto-loaded byplugin/kiritan.lua, ports the VS Code extension'sdiagnostics.cjsapproach exactly: shells out to the workspace's own locally-installedkiritan check --jsonvianpx --no-installand sets realvim.diagnosticentries from the result. Plain Vim has nothing resemblingvim.diagnostic/vim.systemto port this to — and needs no explicit guard against loading it anyway, since Vim's own runtime loader only globsplugin/*.vim, never.lua, soplugin/kiritan.luais simply never read under Vim in the first place (confirmed directly: adding it left Vim's own:scriptnamescompletely unaware of its existence, no error, no side effect). Verified with a real headlessnvim --cleanprocess the same way as the Vimscript side, which caught a real bug before it shipped:kiritan checkexits 1 whenever any issue matchescheck.failOn— exactly the case with something worth diagnosing — but the check's callback was discarding the result whenever the exit code was non-zero, so it would have silently reported nothing for the one scenario that mattered. The same bug, for the same reason (Node'sexecrejects on any non-zero exit but the rejection still carries.stdout), was hiding in the VS Code extension's owndiagnostics.cjsand got fixed alongside this. Releases are lighter than the other components too, since there's nothing to build:release-vim.ymljust runs the test suite and tags the commit askiritan-vim@<version>with a--generate-notesGitHub Release (no attached asset). There's nopackage.jsonhere to hold a current version to bump from, so it finds the latest existingkiritan-vim@*tag and reusesnpm version's own semver logic against a throwawaypackage.json— the samepatch/minor/major/prereleasekeyword or explicit-versionversioninput asrelease.yml. - Wiring
plugins.stores: done.build/check/translate/extractall dispatch a source whosestrategymatches aplugins.storeskey to thatTranslationStore'sread/write/status(chapter 4, chapter 11) instead of throwing — the twoTranslatedContentshapes it declares turned out to generalize the built-ins cleanly: a"full-text"result is treated sidecar-style (parsed fresh as the whole document), a"segments"result (or nothing stored yet) catalog-style (fed intorenderForLocale's existing per-id fallback, so no new fallback logic was needed). Staleness is left entirely to the store's ownstatus()—check/translatetrust it outright rather than trying to recompute it the way the built-insidecar/catalogformats do for themselves, since a plugin store is a black box kiritan doesn't own the internals of.checkonly callsstatus(), notread(), so there's no generic "machine-translated, needs review" issue for a plugin store the waycatalog's ownmachineflag produces one — that stays acatalog-specific concept for now.translate/extractboth no-op for a store with nowrite(a read-only store, e.g. one backed by an external TMS kiritan can only read from). Astrategymatching neither a built-in nor a registered store now throws in all four commands, not justbuildas before — a deliberate tightening, since a customstrategytypo (e.g."catalogg") was always a mistake with no legitimate use, and there's now an actual registration mechanism to check it against. - Wiring
plugins.renderers: done. The blocker was that the originally declaredRenderer(parse(sourceText): { raw: string },reassemble(doc, translated: string)) couldn't represent the mdast treerenderForLocale/collectCatalogSegmentsoperate on end to end. It was redefined as aparse(source): Root/stringify(tree): stringpair instead, so a new format parses into the existing tree rather than getting a parallel pipeline: directive resolution, interpolation, and switcher insertion all keep working unchanged.build/check/translate/extractresolve a renderer per source file (chapter 6) and go through it for every parse and stringify. Two optional capabilities cover formats unlike Markdown:supportsDirectives: falseskips directive resolution and switcher insertion, and an absentcommentmeans thekiritan:hash/kiritan:untranslatedmarkers (which are<!-- ... -->comments in Markdown) simply aren't written, so such a format gets no staleness detection.kiritan:hashis now matched wherever it appears rather than only inside an HTML comment, so a customcommentcan wrap it however it likes. - Front-matter protection: done. A leading YAML block is one opaque
yamlnode in the mdast tree, so it survives parse/stringify verbatim and interpolation never reaches it. AtranslateFrontmatteroption (per-locale front-matter values) was considered but dropped for now — there's no place ininline/catalogto put a locale-specific value, so it only ever mattered forsidecar, where the translated file already owns its own front matter. kiritan verify(andverify()in the API): done. It checks that each generated document matches whatbuildwould write from the current base files and config, comparing hashes (hashText, line endings normalized so anautocrlfcheckout isn't a false alarm) and reporting both, and writes nothing.buildwas split intorenderOutputs()(everything up to the write) and the write itself so the two share one code path — there's no separate "expected output" logic that could drift from whatbuildreally does. Amismatchcovers both a base file that changed since the last build and a generated file edited by hand;missinga document that was never generated. It answers a different question fromcheck, which is about missing/stale translations, so it's a separate command rather than anothercheckissue kind. Note that for asidecartranslation the expected output is the file re-rendered throughbuild, so a hand-written translation whose formattingbuildwould normalize also shows as a mismatch — the same filebuildwould rewrite.textrenderer: done (chapter 6) — and it's the second renderer theplugins.renderersitem above was waiting on to validate the interface's real shape. It exercised both optional capabilities (supportsDirectives: false, nocomment), and needed nothing beyond them.mdxrenderer: done (chapter 6).%{name}interpolation is the one thing that doesn't carry over, and can't without changing MDX's own parse.