# kiritan
**English** | [日本語](README.ja.md)
> In addition to standard scopes, an internationalization (i18n) utility for Markdown and other plain text documents
[](https://www.npmjs.com/package/kiritan) [](https://github.com/otnc/kiritan/actions) [](https://github.com/otnc/kiritan/blob/main/LICENSE) [](https://www.npmjs.com/package/kiritan)
> [!Warning]
>
> Kiritan is early and under active development (pre-1.0); the config shape and APIs may still change. The full design is written up in [docs/DESIGN.md](https://github.com/otnc/kiritan/blob/main/docs/DESIGN.md).
## Install
```sh
npm install kiritan
```
## Usage
```md
# Kiritan
:::kiritan{locale=en}
## Usage
English content.
:::
:::kiritan{locale=ja}
## 使い方
日本語のコンテンツ。
:::
```
```ts
// .kiritanconfig
import { defineConfig } from "kiritan";
export default defineConfig({
locales: { default: "en", list: ["en", "ja"] },
sources: [{ glob: "README.base.md", strategy: "inline" }],
naming: { preset: "dot" }, // README.md (default locale) / README.ja.md
});
```
```sh
npx kiritan build
# wrote README.md
# wrote README.ja.md
```
A language switcher (`**English** | [日本語](README.ja.md)`) is inserted automatically — see [docs/DESIGN.md](https://github.com/otnc/kiritan/blob/main/docs/DESIGN.md) chapter 6.1.
Programmatic API:
```ts
import { build, resolveConfig } from "kiritan";
const config = await resolveConfig({ mode: "production" });
await build(config);
```
`resolveConfig` discovers and merges the `*.kiritanconfig` cascade for the current directory and fills in the documented defaults. See [docs/DESIGN.md](https://github.com/otnc/kiritan/blob/main/docs/DESIGN.md) chapter 3 for the full config shape and cascade rules.
## Commands
| Command | What it does |
| --- | --- |
| `kiritan init` | Scaffolds `.kiritanconfig`, `base/README.base.md`, and a `.gitignore` entry for `local.kiritanconfig` in a fresh project. Leaves existing files alone unless `--force` is passed |
| `kiritan build` | Builds localized documents from every configured source |
| `kiritan check` | Reports missing/stale/machine-translated content; exits non-zero in CI when `check.failOn` matches |
| `kiritan verify` | Checks that every generated document matches what `build` would write today (by hash), without writing anything; exits non-zero in CI on a mismatch or a missing file. Catches an out-of-date or hand-edited generated doc |
| `kiritan translate` | Fills in missing/stale translations via `translate.middlewares` — only when `translate.auto` is `true`, otherwise it reports that nothing ran. Works for `sidecar`, `catalog` and `inline` (which writes new `:::kiritan{locale=...}` blocks into the base file); what it writes is marked as machine-translated until you review it |
| `kiritan extract` | Scaffolds new `catalog`-strategy ids and reports orphaned ones |
| `kiritan typegen` | Merges `runtime.sources` into one namespaced `ResourceModule` and writes its type declaration ([docs/DESIGN.md](https://github.com/otnc/kiritan/blob/main/docs/DESIGN.md) chapter 9.6) |
Every command except `kiritan init` accepts `--mode ` and `--config ` to adjust which config layers are applied — there's no config to layer yet before `init` has run. `build`/`check`/`translate`/`extract` also accept `--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.
Every command also accepts `--lang `, picking the CLI's own display language — command/option descriptions, `--help` output, and the CLI's own plain-text output lines (not `--json`, which stays machine-readable regardless). This is unrelated to `--locale`, which picks which *document* locale a run acts on. Without `--lang`, it falls back to the `KIRITAN_LANG`/`LC_ALL`/`LC_MESSAGES`/`LANG` environment variables, then `en`.
## Requirements
- Node.js >= 18.3
## Related packages
| Package (npm) | GitHub | What it is |
| --- | --- | --- |
| [`@kiritan/runtime`](https://www.npmjs.com/package/@kiritan/runtime) | [packages/runtime](https://github.com/otnc/kiritan/tree/main/packages/runtime) | The minimal `t(key, params)` runtime, with no build-time dependencies |
| [`@kiritan/middleware`](https://www.npmjs.com/package/@kiritan/middleware) | [packages/middleware](https://github.com/otnc/kiritan/tree/main/packages/middleware) | Turns any translate function into a `translate.middlewares` entry: protects code/URLs/`%{name}`, splits, batches, retries, caches |
| [`@kiritan/free-translate`](https://www.npmjs.com/package/@kiritan/free-translate) | [packages/free-translate](https://github.com/otnc/kiritan/tree/main/packages/free-translate) | Middlewares that need no API key (MyMemory, Google's keyless endpoint, self-hosted LibreTranslate and Google Apps Script) |
| [`@kiritan/deepl`](https://www.npmjs.com/package/@kiritan/deepl) | [packages/deepl](https://github.com/otnc/kiritan/tree/main/packages/deepl) | A DeepL middleware |
| [`@kiritan/google-translate`](https://www.npmjs.com/package/@kiritan/google-translate) | [packages/google-translate](https://github.com/otnc/kiritan/tree/main/packages/google-translate) | A Google Cloud Translation middleware |
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](https://github.com/otnc/kiritan/blob/main/CONTRIBUTING.md) for details.
## License
Distributed under the [WTFPL License](https://github.com/otnc/kiritan/blob/main/LICENSE).
> [!Note]
>
> The image files (`.png` / `.gal`) under `assets/` are **not** covered by WTFPL. They may be used for purposes such as introducing this library (e.g. blog posts), but may not be used as an application logo/icon or embedded into any product. See [ASSETS\_LICENSE.md](https://github.com/otnc/kiritan/blob/main/ASSETS_LICENSE.md) for details.