From dda04b9494dc143afa392ac345db81a0137dbbb3 Mon Sep 17 00:00:00 2001 From: "otoneko." Date: Mon, 14 Sep 2026 22:41:15 +0900 Subject: [PATCH] feat(kiritan): wire up plugins.stores for custom TranslationStore strategies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit build/check/translate/extract now dispatch a source whose strategy matches a plugins.stores key to that TranslationStore's read/write/ status instead of throwing. The two TranslatedContent shapes it declares 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 into renderForLocale's existing per-id fallback — no new fallback logic needed. Staleness is left entirely to the store's own status(); check/ translate trust it outright rather than recomputing it the way the built-in sidecar/catalog formats do for themselves, since a plugin store is a black box. check only calls status(), not read(), so there is no generic "machine-translated" issue for a plugin store the way catalog's own machine flag produces one — that stays catalog-specific for now. translate/extract both no-op for a store with no write (a read-only store, e.g. backed by an external TMS). A strategy matching neither a built-in nor a registered store now throws in all four commands, not just build as before — a custom strategy typo was always a mistake with no legitimate use, and there is now an actual registration mechanism to check it against. plugins.renderers stays unwired: the declared Renderer interface (parse/reassemble over raw strings) can't represent the mdast tree the real pipeline depends on end-to-end, and a working design needs an actual second renderer (text/mdx, a separate roadmap item) to validate the interface's real shape against first. --- base/DESIGN.base.md | 18 +- docs/DESIGN.ja.md | 9 +- docs/DESIGN.md | 9 +- packages/kiritan/src/pipeline/build.test.ts | 94 ++++++++++- packages/kiritan/src/pipeline/build.ts | 64 +++++++ packages/kiritan/src/pipeline/check.test.ts | 81 ++++++++- packages/kiritan/src/pipeline/check.ts | 49 +++++- packages/kiritan/src/pipeline/extract.test.ts | 148 ++++++++++++++++- packages/kiritan/src/pipeline/extract.ts | 95 ++++++++++- .../kiritan/src/pipeline/translate.test.ts | 157 +++++++++++++++++- packages/kiritan/src/pipeline/translate.ts | 115 ++++++++++++- 11 files changed, 809 insertions(+), 30 deletions(-) diff --git a/base/DESIGN.base.md b/base/DESIGN.base.md index ede861c..a12202b 100644 --- a/base/DESIGN.base.md +++ b/base/DESIGN.base.md @@ -1199,24 +1199,24 @@ export type { CreateTOptions } from '@kiritan/runtime'; :::kiritan{locale=en} | Kind | Status in v1 | | --- | --- | -| Translation storage strategy | `sidecar` / `inline` / `catalog` are built in, but hardcoded directly into the pipeline rather than dispatched through the declared `TranslationStore` interface. `plugins.stores` isn't wired yet — setting it currently has no effect. | +| 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 | Only `markdown` is implemented; every source is processed as Markdown regardless of extension. `.txt`/`.mdx`, the declared `Renderer` interface, and `plugins.renderers` aren't wired yet — setting `plugins.renderers` currently has no effect. | +| File renderer | Only `markdown` is implemented; every source is processed as Markdown regardless of extension. `.txt`/`.mdx`, the declared `Renderer` interface, and `plugins.renderers` aren't wired yet — setting `plugins.renderers` currently has no effect (see chapter 13 for why this is a separate, still-unscoped piece of work from `plugins.stores` above). | | Language-switcher rendering | Genuinely extensible today via `SwitcherConfig.render` (chapter 6.1). | -`TranslationStore`, `Renderer`, and `plugins.{stores,renderers}` are declared today as the shape a future pluggable version will use, but nothing in v1 reads or calls them yet (tracked in chapter 13). +`plugins.stores` is wired as of chapter 13; `Renderer`/`plugins.renderers` are still declared only as the shape a future pluggable version will use, with nothing in v1 reading or calling them yet. ::: :::kiritan{locale=ja} | 種別 | v1での状況 | | --- | --- | -| 翻訳格納戦略 | `sidecar` / `inline` / `catalog` は組み込みだが、宣言されている `TranslationStore` インターフェース経由ではなく、パイプラインに直接ハードコードされている。`plugins.stores` はまだ配線されておらず、設定しても現状は何も効果が無い。 | +| 翻訳格納戦略 | `sidecar` / `inline` / `catalog` は組み込みでハードコードされているが、それ以外の `strategy` 文字列を使うソースは、`plugins.stores[strategy]` に登録されていれば実際にそこへディスパッチされるようになった(4章、`TranslationStore`) — `build`/`check`/`translate`/`extract` のすべてがこれを呼び出す。組み込みにも登録済みストアにも一致しない `strategy` は、4コマンドすべてで分かりやすいエラーを投げる。 | | ランタイムリソース配置戦略 | `colocated` / `split` / `centralized` / `embedded`(9.1章)は `ResourceSourceConfig.strategy` 経由で実際にディスパッチされている。カスタムの文字列戦略は型としては受け付けるが、処理する実装はまだ無い。 | | 翻訳ミドルウェア | 現状で実際に拡張可能: 組み込みプロバイダは無く、`translate.middlewares` 配列だけで完結する(利用者が自由に実装。`docs/` に実装例を掲載)。 | -| ファイルレンダラー | 実装されているのは `markdown` のみで、拡張子に関わらず全ソースをMarkdownとして処理する。`.txt`/`.mdx`、宣言されている `Renderer` インターフェース、`plugins.renderers` はまだ配線されておらず、`plugins.renderers` を設定しても現状は何も効果が無い。 | +| ファイルレンダラー | 実装されているのは `markdown` のみで、拡張子に関わらず全ソースをMarkdownとして処理する。`.txt`/`.mdx`、宣言されている `Renderer` インターフェース、`plugins.renderers` はまだ配線されておらず、`plugins.renderers` を設定しても現状は何も効果が無い(上の `plugins.stores` とは別に、まだスコープの定まっていない作業である理由は13章を参照)。 | | 言語切り替えリンクの描画 | `SwitcherConfig.render`(6.1章)経由で現状も実際に拡張可能。 | -`TranslationStore`・`Renderer`・`plugins.{stores,renderers}` は、将来のプラグイン可能なバージョンが使う形として現時点でも宣言されているが、v1ではまだ何もこれらを読み書きしていない(13章で追跡)。 +`plugins.stores` は13章の通り配線済み。`Renderer`/`plugins.renderers` は、将来のプラグイン可能なバージョンが使う形として現時点でも宣言されているだけで、v1ではまだ何もこれらを読み書きしていない。 ::: :::kiritan{locale=en} @@ -1247,7 +1247,8 @@ None at this time. Anything that comes up during implementation will be appended - **A per-command `--locale` flag**: done, for `build`/`check`/`translate`/`extract` — each accepts `--locale ` to restrict a run to one locale instead of every locale in `locales.list`, via a shared `resolveTargetLocales` helper that also rejects a locale not in `locales.list` with 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 typegen` doesn'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`](../extensions/vscode) — in progress. Syntax highlighting for `:::kiritan{...}`/`::kiritan{...}` blocks (a declarative TextMate grammar injected into Markdown, no compiled extension code) is done. Published as `otoneko1102.kiritan` (a VS Code extension identifier can't contain a `/`, ruling out `@kiritan/vscode` as originally envisioned; its `package.json` `"name"` is the plain `"kiritan"`). Since that collides with the CLI package's own npm name, it lives under `extensions/` rather than `packages/` and so is never picked up by the root `"workspaces": ["packages/*"]` glob — its build/test tooling lives in the root `package.json`'s `devDependencies` instead (chapter 2.1). Highlighting for `%{name}` (and its `\%{name}` escape), folding for `:::kiritan` blocks (colon-count matched via a small stack, so nesting other directives around a kiritan block doesn't confuse it), jump-to-definition from `:::kiritan{#}` to its entry in the sibling `..catalog.json`, undefined-`%{name}`-variable warnings, and inline `missing`/`stale`/`machine` indicators are all done — the last two settled the "bigger design question" the others were left waiting on: rather than requiring `kiritan`'s internals in-process (real crash/version-skew risk from a broken or mismatched project install), `diagnostics.cjs` spawns the workspace's own locally-installed `kiritan check --json` as a child process, the same approach ESLint/Prettier's editor integrations use for their own local installs. `npx --no-install` means a project that doesn't depend on `kiritan` at all is silently skipped rather than triggering a surprise network install. `kiritan check` gained a `--json` flag and `CheckIssue.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, matching `interpolation.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 custom `interpolation.delimiters` still gets everything else. It also registers `*.kiritanconfig` as its own language, delegating highlighting to `source.js` via a TextMate `include` and reusing JavaScript's bracket/comment/indent rules via its own `language-configuration.json` — this is why config files are named `*.kiritanconfig` rather than `.kiritan.mjs` (chapter 3.1): a file icon theme's own rules always beat a language's fallback icon, so keeping a real `.mjs` extension 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 actual `javascript`/`typescript` language ids, and giving `*.kiritanconfig` the real `javascript` id would let vscode-icons' own language-based icon rule override the custom one. `extension.cjs` bridges this: it mirrors a `*.kiritanconfig` document's content into an in-memory `javascript` document (a `TextDocumentContentProvider`-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`](../extensions/vim) — highlighting done, everything past that still open. 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.vim` highlights `:::kiritan{...}`/`::kiritan{...}` directives and `%{name}` interpolation by layering onto the built-in `markdown` syntax, the Vimscript equivalent of the VS Code extension's TextMate grammar injection, and `ftdetect/kiritanconfig.vim` assigns the real `javascript` filetype to `*.kiritanconfig` files directly — no need for VS Code's `kiritanconfig`-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 headless `vim -u NONE` process (`synID()`/`synIDattr()` at specific positions), not just asserted against the `.vim` source, the same rigor the VS Code extension's grammar tests use — this actually caught a real gotcha along the way: Vim's `:syntax on` autocommand only ever runs `runtime! syntax/.vim` against each `'runtimepath'` entry's own `syntax/` subdirectory, never a nested `after/syntax/`, so a plugin's `after/` subdirectory has to be added to `'runtimepath'` as its *own* separate entry (which plugin managers do automatically) for `after/syntax/markdown.vim` to load at all. Folding (`after/ftplugin/markdown.vim` sets `'foldexpr'` to `autoload/kiritan.vim`'s `kiritan#FoldExpr`, precomputing every line's fold level with the same colon-count-stack algorithm as `folding-core.cjs`, cached per buffer against `b:changedtick`) and jump-to-catalog-entry (`:KiritanJumpToCatalog`, bound to nothing by default — see the plugin's README for wiring up `(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 inline `missing`/`stale`/`machine` indicators are done too, but Neovim-only (`nvim-0.10+`) — `lua/kiritan/diagnostics.lua`, auto-loaded by `plugin/kiritan.lua`, ports the VS Code extension's `diagnostics.cjs` approach exactly: shells out to the workspace's own locally-installed `kiritan check --json` via `npx --no-install` and sets real `vim.diagnostic` entries from the result. Plain Vim has nothing resembling `vim.diagnostic`/`vim.system` to port this to — and needs no explicit guard against loading it anyway, since Vim's own runtime loader only globs `plugin/*.vim`, never `.lua`, so `plugin/kiritan.lua` is simply never read under Vim in the first place (confirmed directly: adding it left Vim's own `:scriptnames` completely unaware of its existence, no error, no side effect). Verified with a real headless `nvim --clean` process the same way as the Vimscript side, which caught a real bug before it shipped: `kiritan check` exits 1 whenever any issue matches `check.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's `exec` rejects on any non-zero exit but the rejection still carries `.stdout`), was hiding in the VS Code extension's own `diagnostics.cjs` and got fixed alongside this. Releases are lighter than the other components too, since there's nothing to build: `release-vim.yml` just runs the test suite and tags the commit as `kiritan-vim@` with a `--generate-notes` GitHub Release (no attached asset). There's no `package.json` here to hold a current version to bump from, so it finds the latest existing `kiritan-vim@*` tag and reuses `npm version`'s own semver logic against a throwaway `package.json` — the same `patch`/`minor`/`major`/`prerelease` keyword or explicit-version `version` input as `release.yml`. -- **Wiring `plugins.stores`/`plugins.renderers`**: making the declared `TranslationStore`/`Renderer` interfaces (chapter 11) actually pluggable, instead of `sidecar`/`inline`/`catalog` and the Markdown renderer being hardcoded into the pipeline as they are in v1. +- **Wiring `plugins.stores`**: done. `build`/`check`/`translate`/`extract` all dispatch a source whose `strategy` matches a `plugins.stores` key to that `TranslationStore`'s `read`/`write`/`status` (chapter 4, chapter 11) instead of throwing — the two `TranslatedContent` shapes 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 into `renderForLocale`'s existing per-id fallback, so no new fallback logic was needed). Staleness is left entirely to the store's own `status()` — `check`/`translate` trust it outright rather than trying to recompute it the way the built-in `sidecar`/`catalog` formats do for themselves, since a plugin store is a black box kiritan doesn't own the internals of. `check` only calls `status()`, not `read()`, so there's no generic "machine-translated, needs review" issue for a plugin store the way `catalog`'s own `machine` flag produces one — that stays a `catalog`-specific concept for now. `translate`/`extract` both no-op for a store with no `write` (a read-only store, e.g. one backed by an external TMS kiritan can only read from). A `strategy` matching neither a built-in nor a registered store now throws in all four commands, not just `build` as before — a deliberate tightening, since a custom `strategy` typo (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`**: still not done, and deliberately scoped separately from `plugins.stores` above — the declared `Renderer` interface (`parse(sourceText): { raw: string }`, `reassemble(doc, translated: string)`) has no way to represent the mdast tree `directive/render.ts`'s `renderForLocale`/`collectCatalogSegments`/etc. actually operate on end-to-end, so it can't be wired against the real pipeline as declared. A working design needs an actual second renderer (see the next item) to validate the interface's real shape against, not just the bare `strategies: StoreStrategy[]` field it already has. - **`text`/`mdx` renderers and front-matter protection**: v1 only implements the `markdown` renderer; `.txt`/`.mdx` support and `translateFrontmatter` (chapter 6) are design-stage only. ::: :::kiritan{locale=ja} @@ -1257,6 +1258,7 @@ None at this time. Anything that comes up during implementation will be appended - **コマンド共通の `--locale` フラグ**: 対応済み。`build`/`check`/`translate`/`extract` がそれぞれ `--locale ` を受け付け、実行対象を `locales.list` 全体ではなく1ロケールに絞れる。共通のヘルパー `resolveTargetLocales` を介しており、`locales.list` に無いロケールを指定した場合は分かりやすいエラーで弾く。`build` のswitcherリンクは `--locale` の指定に関わらず設定済みの全ロケールを表示し続ける — 他のロケールのファイルは既にディスク上に存在しており、switcherは今回の実行だけを説明するものではないため。`kiritan typegen` だけは対応しない — 常に全ロケールを1つのランタイムモジュールに集約するコマンドのため、1ロケールに絞る意味のある方法が無い。 - **VS Code 拡張機能**: [`extensions/vscode`](../extensions/vscode) —対応中。`:::kiritan{...}`/`::kiritan{...}` ブロックのシンタックスハイライト(Markdownに注入する宣言的なTextMate文法のみ、コンパイル済み拡張機能コードは無し)は完了。`otoneko1102.kiritan` として公開する(VS Code の拡張機能識別子に `/` を含められないため、当初構想していた `@kiritan/vscode` は使えず、`package.json` の `"name"` はそのまま `"kiritan"` にしている)。これはCLIパッケージのnpm名と衝突するため、`packages/` ではなく `extensions/` 配下に置いており、ルートの `"workspaces": ["packages/*"]` には拾われない — ビルド・テストに必要なツールはルートの `package.json` の `devDependencies` に置いている(2.1章)。`%{name}`(とそのエスケープ形式 `\%{name}`)のハイライト、`:::kiritan` ブロックの折りたたみ(小さなスタックでコロンの個数を対応させているため、他のディレクティブがネストしていても混乱しない)、`:::kiritan{#}` から隣接する `..catalog.json` 内の該当エントリへのジャンプ、未定義の`%{name}`変数の警告、`missing`/`stale`/`machine`のインライン表示は、いずれも完了 — 最後の2つが、それ以外の機能が待っていた「より大きな設計判断」を決着させた。`kiritan`の内部実装をプロセス内で直接読み込む(壊れた・バージョンの合わないプロジェクトのインストールがそのままクラッシュ/不整合につながる実際のリスクがある)代わりに、`diagnostics.cjs`はワークスペース自身にローカルインストールされた`kiritan check --json`を子プロセスとして起動する — ESLint/Prettierのエディタ統合が自身のローカルインストールに対して行っているのと同じアプローチ。`npx --no-install`により、`kiritan`に依存しないプロジェクトでは意図せぬネットワーク経由のインストールが走らず、単に何もしない。`kiritan check`はこのために`--json`フラグと`CheckIssue.id`(catalogセグメントidがある場合)を新たに備えた。コードフェンス内やインラインコードスパン内の`%{name}`は、`interpolation.skipCodeBlocks`の既定動作に合わせて検出対象外にしている — これは拡張機能自身のREADME(この記法をリテラルな例として示している)に対して実際にテストして見つかった問題だった。未定義変数の検出は既定の`%{`/`}`区切り文字にのみ対応しており、`interpolation.delimiters`をカスタマイズしているプロジェクトでも他の機能はそのまま使える。あわせて `*.kiritanconfig` を独自言語として登録し、ハイライトはTextMateの `include` で `source.js` に委譲、括弧・コメント・インデントのルールも独自の `language-configuration.json` でJavaScript相当にしている — これが設定ファイルを `.kiritan.mjs` ではなく `*.kiritanconfig` と命名した理由でもある(3.1章)。ファイルアイコンテーマ自身のルールは常に言語のフォールバックアイコンより優先されるため、実在する `.mjs` 拡張子のままではvscode-iconsのようなテーマで永久に汎用的なJavaScriptアイコンのままになってしまう。見たことの無いファイル名に対して具体的なルールを持つアイコンテーマは存在しないため、この言語登録だけで、テーマ側の個別設定なしにあらゆるアイコンテーマでKiritan固有のアイコンが表示される。ただし本物のコード補完には文法だけでは足りない — 組み込みのTypeScript/JavaScript言語サービスは実際の `javascript`/`typescript` 言語IDにしか反応せず、かといって `*.kiritanconfig` に本物の `javascript` IDを与えるとvscode-icons自身の言語ベースのアイコンルールがカスタムアイコンを上書きしてしまう。`extension.cjs` はこれを橋渡しする — `*.kiritanconfig` ドキュメントの内容を、メモリ上の `javascript` ドキュメント(`TextDocumentContentProvider` による仮想ドキュメント。untitledドキュメントではない — untitledは実体のある編集可能バッファでVS Codeが未保存として数えてしまうため、この橋渡しの初期版では誤ってuntitledを使っていた)に複製し、補完リクエストをVS Code組み込みのプロバイダーへ転送することで、アイコンとフルIntelliSenseを両立させている。 - **Vim/Neovim プラグイン**: [`extensions/vim`](../extensions/vim) — ハイライトは完了、それ以外はまだ未着手。ここで当初想定していた共有tree-sitter文法/LSPではなく、素のVimscriptで実装した — それは実際に投資が必要な選択肢であり、当面の目標(VS Code拡張機能自身のv1に合わせる)にはまだ必要なかったため。`after/syntax/markdown.vim` は組み込みの `markdown` 文法に重ねる形で `:::kiritan{...}`/`::kiritan{...}` ディレクティブと `%{name}` 補間をハイライトする、VS Code拡張機能のTextMate文法注入に相当する仕組み。`ftdetect/kiritanconfig.vim` は `*.kiritanconfig` ファイルに本物の `javascript` filetypeを直接設定する — Vim/Neovimのアイコンエコシステムにはvscode-iconsの言語ルールと同じトレードオフが無いため、VS Code拡張機能の `kiritanconfig` 独自言語という回避策は不要(3.1章)。実際のヘッドレス `vim -u NONE` プロセス(`synID()`/`synIDattr()` で特定位置を問い合わせる)に対して検証しており、単に `.vim` ソースへのアサーションではない — VS Code拡張機能のグラマーテストと同じ厳密さ。この過程で実際に見つかった落とし穴: Vimの `:syntax on` のautocommandは、`'runtimepath'` の各エントリ自身の `syntax/` サブディレクトリに対してのみ `runtime! syntax/.vim` を実行し、ネストした `after/syntax/` は決して見ない — そのため、プラグインの `after/` サブディレクトリを `'runtimepath'` に**別エントリとして**追加しない限り(プラグインマネージャーは自動的に行う)、`after/syntax/markdown.vim` は一切読み込まれない。折りたたみ(`after/ftplugin/markdown.vim` が `'foldexpr'` を `autoload/kiritan.vim` の `kiritan#FoldExpr` に設定し、`folding-core.cjs` と同じコロン個数スタックのアルゴリズムで各行の折りたたみレベルを事前計算、バッファごとに `b:changedtick` を鍵にキャッシュする)とcatalogエントリへのジャンプ(`:KiritanJumpToCatalog`。既定では何のキーにも割り当てず — 詳細はプラグインのREADMEの `(kiritan-jump-to-catalog)` の配線方法を参照。複数ロケールのcatalogが一致する場合はquickfixリストに反映)も完了しており、同じく実際のvimプロセスで検証している。未定義の`%{name}`検出と`missing`/`stale`/`machine`のインライン表示も完了しているが、Neovim限定(`nvim-0.10+`)——`lua/kiritan/diagnostics.lua`(`plugin/kiritan.lua`が自動読み込み)は、VS Code拡張機能の`diagnostics.cjs`のアプローチをそのまま移植している。ワークスペース自身にローカルインストールされた`kiritan check --json`を`npx --no-install`経由で実行し、その結果を実際の`vim.diagnostic`として設定する。素のVimには`vim.diagnostic`/`vim.system`に相当するものが無く、そもそも明示的な読み込み防止すら不要 — Vim自身のランタイムローダーは`plugin/*.vim`しか見ず`.lua`は一切見ないため、`plugin/kiritan.lua`はVim上では最初から読み込まれない(実際に確認済み: 追加してもVimの`:scriptnames`には一切現れず、エラーも副作用も無かった)。Vimscript側と同様、実際のヘッドレス`nvim --clean`プロセスで検証しており、公開前に実際のバグを発見した: `kiritan check`は`check.failOn`に一致する問題がある場合(まさに診断したいケース)に終了コード1を返すが、checkのコールバックが終了コードが非ゼロの場合に結果を破棄していたため、最も重要なシナリオで何も報告されなくなってしまっていた。同じ理由(Node's `exec`は非ゼロ終了で常にrejectするが、reject後のエラーオブジェクトにも`.stdout`は残っている)による同じバグがVS Code拡張機能自身の`diagnostics.cjs`にも潜んでおり、あわせて修正した。リリースも他のコンポーネントより軽量 — ビルドすべきものが無いため、`release-vim.yml` はテストスイートを実行してコミットに `kiritan-vim@` タグを打ち、`--generate-notes` でGitHub Releaseを作成するだけ(添付ファイルなし)。バンプ元となる現在のバージョンを保持する `package.json` が無いため、既存の `kiritan-vim@*` タグのうち最新のものを起点にし、使い捨ての `package.json` で `npm version` 自身のsemverロジックを借用する — `release.yml` と同じ `patch`/`minor`/`major`/`prerelease` キーワードまたは明示的なバージョンの `version` 入力。 -- **`plugins.stores`/`plugins.renderers` の配線**: 宣言されている `TranslationStore`/`Renderer` インターフェース(11章)を実際にプラガブルにする。v1では `sidecar`/`inline`/`catalog` とMarkdownレンダラーがパイプラインに直接ハードコードされている。 +- **`plugins.stores` の配線**: 対応済み。`build`/`check`/`translate`/`extract` はすべて、`strategy` が `plugins.stores` のキーに一致するソースを、例外を投げる代わりにその `TranslationStore` の `read`/`write`/`status`(4章・11章)へディスパッチするようになった — 宣言されている2つの `TranslatedContent` 形状は、組み込みの2戦略をきれいに一般化できることが分かった: `"full-text"` の結果はsidecar方式で扱う(独立したドキュメントとして新規にparseする)。`"segments"` の結果(または何も保存されていない場合)はcatalog方式で扱う(`renderForLocale` 既存のper-idフォールバックにそのまま流し込むため、新しいフォールバック処理は不要だった)。stalenessの判定は完全にストア自身の `status()` に委ねる — `check`/`translate` はその返り値をそのまま信用し、組み込みの `sidecar`/`catalog` が自分自身のために行っているような再計算はしない。プラグインストアはkiritanが中身を把握できないブラックボックスだからである。`check` は `status()` のみを呼び `read()` は呼ばないため、`catalog` の `machine` フラグが生む「machine翻訳につき要レビュー」に相当する汎用issueはプラグインストアには存在しない — これは当面 `catalog` 固有の概念のままとする。`translate`/`extract` はどちらも `write` の無いストア(kiritanから読み取ることしかできない、外部TMSに裏付けられたストア等)に対しては何もしない。組み込みにも登録済みストアにも一致しない `strategy` は、以前は `build` だけが投げていた例外を、今や4コマンドすべてが投げるようになった — これは意図的な厳格化で、カスタム `strategy` のタイプミス(例: `"catalogg"`)は元々常に単なる設定ミスであり、今や実際にそれを判定するための登録機構が存在するようになったため。 +- **`plugins.renderers` の配線**: まだ未対応で、上の `plugins.stores` とは意図的に別スコープとしている — 宣言されている `Renderer` インターフェース(`parse(sourceText): { raw: string }`、`reassemble(doc, translated: string)`)には、`directive/render.ts` の `renderForLocale`/`collectCatalogSegments` 等が最初から最後まで実際に操作しているmdastツリーを表現する手段が無く、宣言通りの形では実際のパイプラインに対して配線しようがない。実用的な設計にするには、インターフェースの本当に必要な形を検証するための実際の2つ目のレンダラー(次の項目を参照)が必要であり、既に持っている `strategies: StoreStrategy[]` フィールドだけでは足りない。 - **`text`/`mdx` レンダラーとfront matter保護**: v1で実装されているレンダラーは `markdown` のみで、`.txt`/`.mdx` 対応や `translateFrontmatter`(6章)はまだ設計段階。 ::: diff --git a/docs/DESIGN.ja.md b/docs/DESIGN.ja.md index dcb6277..800a208 100644 --- a/docs/DESIGN.ja.md +++ b/docs/DESIGN.ja.md @@ -630,13 +630,13 @@ export type { CreateTOptions } from '@kiritan/runtime'; | 種別 | v1での状況 | | --- | --- | -| 翻訳格納戦略 | `sidecar` / `inline` / `catalog` は組み込みだが、宣言されている `TranslationStore` インターフェース経由ではなく、パイプラインに直接ハードコードされている。`plugins.stores` はまだ配線されておらず、設定しても現状は何も効果が無い。 | +| 翻訳格納戦略 | `sidecar` / `inline` / `catalog` は組み込みでハードコードされているが、それ以外の `strategy` 文字列を使うソースは、`plugins.stores[strategy]` に登録されていれば実際にそこへディスパッチされるようになった(4章、`TranslationStore`) — `build`/`check`/`translate`/`extract` のすべてがこれを呼び出す。組み込みにも登録済みストアにも一致しない `strategy` は、4コマンドすべてで分かりやすいエラーを投げる。 | | ランタイムリソース配置戦略 | `colocated` / `split` / `centralized` / `embedded`(9.1章)は `ResourceSourceConfig.strategy` 経由で実際にディスパッチされている。カスタムの文字列戦略は型としては受け付けるが、処理する実装はまだ無い。 | | 翻訳ミドルウェア | 現状で実際に拡張可能: 組み込みプロバイダは無く、`translate.middlewares` 配列だけで完結する(利用者が自由に実装。`docs/` に実装例を掲載)。 | -| ファイルレンダラー | 実装されているのは `markdown` のみで、拡張子に関わらず全ソースをMarkdownとして処理する。`.txt`/`.mdx`、宣言されている `Renderer` インターフェース、`plugins.renderers` はまだ配線されておらず、`plugins.renderers` を設定しても現状は何も効果が無い。 | +| ファイルレンダラー | 実装されているのは `markdown` のみで、拡張子に関わらず全ソースをMarkdownとして処理する。`.txt`/`.mdx`、宣言されている `Renderer` インターフェース、`plugins.renderers` はまだ配線されておらず、`plugins.renderers` を設定しても現状は何も効果が無い(上の `plugins.stores` とは別に、まだスコープの定まっていない作業である理由は13章を参照)。 | | 言語切り替えリンクの描画 | `SwitcherConfig.render`(6.1章)経由で現状も実際に拡張可能。 | -`TranslationStore`・`Renderer`・`plugins.{stores,renderers}` は、将来のプラグイン可能なバージョンが使う形として現時点でも宣言されているが、v1ではまだ何もこれらを読み書きしていない(13章で追跡)。 +`plugins.stores` は13章の通り配線済み。`Renderer`/`plugins.renderers` は、将来のプラグイン可能なバージョンが使う形として現時点でも宣言されているだけで、v1ではまだ何もこれらを読み書きしていない。 ## 12. 未決事項(実装しながら詰める) @@ -650,5 +650,6 @@ export type { CreateTOptions } from '@kiritan/runtime'; - **コマンド共通の `--locale` フラグ**: 対応済み。`build`/`check`/`translate`/`extract` がそれぞれ `--locale ` を受け付け、実行対象を `locales.list` 全体ではなく1ロケールに絞れる。共通のヘルパー `resolveTargetLocales` を介しており、`locales.list` に無いロケールを指定した場合は分かりやすいエラーで弾く。`build` のswitcherリンクは `--locale` の指定に関わらず設定済みの全ロケールを表示し続ける — 他のロケールのファイルは既にディスク上に存在しており、switcherは今回の実行だけを説明するものではないため。`kiritan typegen` だけは対応しない — 常に全ロケールを1つのランタイムモジュールに集約するコマンドのため、1ロケールに絞る意味のある方法が無い。 - **VS Code 拡張機能**: [`extensions/vscode`](../extensions/vscode) —対応中。`:::kiritan{...}`/`::kiritan{...}` ブロックのシンタックスハイライト(Markdownに注入する宣言的なTextMate文法のみ、コンパイル済み拡張機能コードは無し)は完了。`otoneko1102.kiritan` として公開する(VS Code の拡張機能識別子に `/` を含められないため、当初構想していた `@kiritan/vscode` は使えず、`package.json` の `"name"` はそのまま `"kiritan"` にしている)。これはCLIパッケージのnpm名と衝突するため、`packages/` ではなく `extensions/` 配下に置いており、ルートの `"workspaces": ["packages/*"]` には拾われない — ビルド・テストに必要なツールはルートの `package.json` の `devDependencies` に置いている(2.1章)。`%{name}`(とそのエスケープ形式 `\%{name}`)のハイライト、`:::kiritan` ブロックの折りたたみ(小さなスタックでコロンの個数を対応させているため、他のディレクティブがネストしていても混乱しない)、`:::kiritan{#}` から隣接する `..catalog.json` 内の該当エントリへのジャンプ、未定義の`%{name}`変数の警告、`missing`/`stale`/`machine`のインライン表示は、いずれも完了 — 最後の2つが、それ以外の機能が待っていた「より大きな設計判断」を決着させた。`kiritan`の内部実装をプロセス内で直接読み込む(壊れた・バージョンの合わないプロジェクトのインストールがそのままクラッシュ/不整合につながる実際のリスクがある)代わりに、`diagnostics.cjs`はワークスペース自身にローカルインストールされた`kiritan check --json`を子プロセスとして起動する — ESLint/Prettierのエディタ統合が自身のローカルインストールに対して行っているのと同じアプローチ。`npx --no-install`により、`kiritan`に依存しないプロジェクトでは意図せぬネットワーク経由のインストールが走らず、単に何もしない。`kiritan check`はこのために`--json`フラグと`CheckIssue.id`(catalogセグメントidがある場合)を新たに備えた。コードフェンス内やインラインコードスパン内の`%{name}`は、`interpolation.skipCodeBlocks`の既定動作に合わせて検出対象外にしている — これは拡張機能自身のREADME(この記法をリテラルな例として示している)に対して実際にテストして見つかった問題だった。未定義変数の検出は既定の`%{`/`}`区切り文字にのみ対応しており、`interpolation.delimiters`をカスタマイズしているプロジェクトでも他の機能はそのまま使える。あわせて `*.kiritanconfig` を独自言語として登録し、ハイライトはTextMateの `include` で `source.js` に委譲、括弧・コメント・インデントのルールも独自の `language-configuration.json` でJavaScript相当にしている — これが設定ファイルを `.kiritan.mjs` ではなく `*.kiritanconfig` と命名した理由でもある(3.1章)。ファイルアイコンテーマ自身のルールは常に言語のフォールバックアイコンより優先されるため、実在する `.mjs` 拡張子のままではvscode-iconsのようなテーマで永久に汎用的なJavaScriptアイコンのままになってしまう。見たことの無いファイル名に対して具体的なルールを持つアイコンテーマは存在しないため、この言語登録だけで、テーマ側の個別設定なしにあらゆるアイコンテーマでKiritan固有のアイコンが表示される。ただし本物のコード補完には文法だけでは足りない — 組み込みのTypeScript/JavaScript言語サービスは実際の `javascript`/`typescript` 言語IDにしか反応せず、かといって `*.kiritanconfig` に本物の `javascript` IDを与えるとvscode-icons自身の言語ベースのアイコンルールがカスタムアイコンを上書きしてしまう。`extension.cjs` はこれを橋渡しする — `*.kiritanconfig` ドキュメントの内容を、メモリ上の `javascript` ドキュメント(`TextDocumentContentProvider` による仮想ドキュメント。untitledドキュメントではない — untitledは実体のある編集可能バッファでVS Codeが未保存として数えてしまうため、この橋渡しの初期版では誤ってuntitledを使っていた)に複製し、補完リクエストをVS Code組み込みのプロバイダーへ転送することで、アイコンとフルIntelliSenseを両立させている。 - **Vim/Neovim プラグイン**: [`extensions/vim`](../extensions/vim) — ハイライトは完了、それ以外はまだ未着手。ここで当初想定していた共有tree-sitter文法/LSPではなく、素のVimscriptで実装した — それは実際に投資が必要な選択肢であり、当面の目標(VS Code拡張機能自身のv1に合わせる)にはまだ必要なかったため。`after/syntax/markdown.vim` は組み込みの `markdown` 文法に重ねる形で `:::kiritan{...}`/`::kiritan{...}` ディレクティブと `%{name}` 補間をハイライトする、VS Code拡張機能のTextMate文法注入に相当する仕組み。`ftdetect/kiritanconfig.vim` は `*.kiritanconfig` ファイルに本物の `javascript` filetypeを直接設定する — Vim/Neovimのアイコンエコシステムにはvscode-iconsの言語ルールと同じトレードオフが無いため、VS Code拡張機能の `kiritanconfig` 独自言語という回避策は不要(3.1章)。実際のヘッドレス `vim -u NONE` プロセス(`synID()`/`synIDattr()` で特定位置を問い合わせる)に対して検証しており、単に `.vim` ソースへのアサーションではない — VS Code拡張機能のグラマーテストと同じ厳密さ。この過程で実際に見つかった落とし穴: Vimの `:syntax on` のautocommandは、`'runtimepath'` の各エントリ自身の `syntax/` サブディレクトリに対してのみ `runtime! syntax/.vim` を実行し、ネストした `after/syntax/` は決して見ない — そのため、プラグインの `after/` サブディレクトリを `'runtimepath'` に**別エントリとして**追加しない限り(プラグインマネージャーは自動的に行う)、`after/syntax/markdown.vim` は一切読み込まれない。折りたたみ(`after/ftplugin/markdown.vim` が `'foldexpr'` を `autoload/kiritan.vim` の `kiritan#FoldExpr` に設定し、`folding-core.cjs` と同じコロン個数スタックのアルゴリズムで各行の折りたたみレベルを事前計算、バッファごとに `b:changedtick` を鍵にキャッシュする)とcatalogエントリへのジャンプ(`:KiritanJumpToCatalog`。既定では何のキーにも割り当てず — 詳細はプラグインのREADMEの `(kiritan-jump-to-catalog)` の配線方法を参照。複数ロケールのcatalogが一致する場合はquickfixリストに反映)も完了しており、同じく実際のvimプロセスで検証している。未定義の`%{name}`検出と`missing`/`stale`/`machine`のインライン表示も完了しているが、Neovim限定(`nvim-0.10+`)——`lua/kiritan/diagnostics.lua`(`plugin/kiritan.lua`が自動読み込み)は、VS Code拡張機能の`diagnostics.cjs`のアプローチをそのまま移植している。ワークスペース自身にローカルインストールされた`kiritan check --json`を`npx --no-install`経由で実行し、その結果を実際の`vim.diagnostic`として設定する。素のVimには`vim.diagnostic`/`vim.system`に相当するものが無く、そもそも明示的な読み込み防止すら不要 — Vim自身のランタイムローダーは`plugin/*.vim`しか見ず`.lua`は一切見ないため、`plugin/kiritan.lua`はVim上では最初から読み込まれない(実際に確認済み: 追加してもVimの`:scriptnames`には一切現れず、エラーも副作用も無かった)。Vimscript側と同様、実際のヘッドレス`nvim --clean`プロセスで検証しており、公開前に実際のバグを発見した: `kiritan check`は`check.failOn`に一致する問題がある場合(まさに診断したいケース)に終了コード1を返すが、checkのコールバックが終了コードが非ゼロの場合に結果を破棄していたため、最も重要なシナリオで何も報告されなくなってしまっていた。同じ理由(Node's `exec`は非ゼロ終了で常にrejectするが、reject後のエラーオブジェクトにも`.stdout`は残っている)による同じバグがVS Code拡張機能自身の`diagnostics.cjs`にも潜んでおり、あわせて修正した。リリースも他のコンポーネントより軽量 — ビルドすべきものが無いため、`release-vim.yml` はテストスイートを実行してコミットに `kiritan-vim@` タグを打ち、`--generate-notes` でGitHub Releaseを作成するだけ(添付ファイルなし)。バンプ元となる現在のバージョンを保持する `package.json` が無いため、既存の `kiritan-vim@*` タグのうち最新のものを起点にし、使い捨ての `package.json` で `npm version` 自身のsemverロジックを借用する — `release.yml` と同じ `patch`/`minor`/`major`/`prerelease` キーワードまたは明示的なバージョンの `version` 入力。 -- **`plugins.stores`/`plugins.renderers` の配線**: 宣言されている `TranslationStore`/`Renderer` インターフェース(11章)を実際にプラガブルにする。v1では `sidecar`/`inline`/`catalog` とMarkdownレンダラーがパイプラインに直接ハードコードされている。 +- **`plugins.stores` の配線**: 対応済み。`build`/`check`/`translate`/`extract` はすべて、`strategy` が `plugins.stores` のキーに一致するソースを、例外を投げる代わりにその `TranslationStore` の `read`/`write`/`status`(4章・11章)へディスパッチするようになった — 宣言されている2つの `TranslatedContent` 形状は、組み込みの2戦略をきれいに一般化できることが分かった: `"full-text"` の結果はsidecar方式で扱う(独立したドキュメントとして新規にparseする)。`"segments"` の結果(または何も保存されていない場合)はcatalog方式で扱う(`renderForLocale` 既存のper-idフォールバックにそのまま流し込むため、新しいフォールバック処理は不要だった)。stalenessの判定は完全にストア自身の `status()` に委ねる — `check`/`translate` はその返り値をそのまま信用し、組み込みの `sidecar`/`catalog` が自分自身のために行っているような再計算はしない。プラグインストアはkiritanが中身を把握できないブラックボックスだからである。`check` は `status()` のみを呼び `read()` は呼ばないため、`catalog` の `machine` フラグが生む「machine翻訳につき要レビュー」に相当する汎用issueはプラグインストアには存在しない — これは当面 `catalog` 固有の概念のままとする。`translate`/`extract` はどちらも `write` の無いストア(kiritanから読み取ることしかできない、外部TMSに裏付けられたストア等)に対しては何もしない。組み込みにも登録済みストアにも一致しない `strategy` は、以前は `build` だけが投げていた例外を、今や4コマンドすべてが投げるようになった — これは意図的な厳格化で、カスタム `strategy` のタイプミス(例: `"catalogg"`)は元々常に単なる設定ミスであり、今や実際にそれを判定するための登録機構が存在するようになったため。 +- **`plugins.renderers` の配線**: まだ未対応で、上の `plugins.stores` とは意図的に別スコープとしている — 宣言されている `Renderer` インターフェース(`parse(sourceText): { raw: string }`、`reassemble(doc, translated: string)`)には、`directive/render.ts` の `renderForLocale`/`collectCatalogSegments` 等が最初から最後まで実際に操作しているmdastツリーを表現する手段が無く、宣言通りの形では実際のパイプラインに対して配線しようがない。実用的な設計にするには、インターフェースの本当に必要な形を検証するための実際の2つ目のレンダラー(次の項目を参照)が必要であり、既に持っている `strategies: StoreStrategy[]` フィールドだけでは足りない。 - **`text`/`mdx` レンダラーとfront matter保護**: v1で実装されているレンダラーは `markdown` のみで、`.txt`/`.mdx` 対応や `translateFrontmatter`(6章)はまだ設計段階。 diff --git a/docs/DESIGN.md b/docs/DESIGN.md index bc252d2..aa7016f 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -630,13 +630,13 @@ export type { CreateTOptions } from '@kiritan/runtime'; | Kind | Status in v1 | | --- | --- | -| Translation storage strategy | `sidecar` / `inline` / `catalog` are built in, but hardcoded directly into the pipeline rather than dispatched through the declared `TranslationStore` interface. `plugins.stores` isn't wired yet — setting it currently has no effect. | +| 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 | Only `markdown` is implemented; every source is processed as Markdown regardless of extension. `.txt`/`.mdx`, the declared `Renderer` interface, and `plugins.renderers` aren't wired yet — setting `plugins.renderers` currently has no effect. | +| File renderer | Only `markdown` is implemented; every source is processed as Markdown regardless of extension. `.txt`/`.mdx`, the declared `Renderer` interface, and `plugins.renderers` aren't wired yet — setting `plugins.renderers` currently has no effect (see chapter 13 for why this is a separate, still-unscoped piece of work from `plugins.stores` above). | | Language-switcher rendering | Genuinely extensible today via `SwitcherConfig.render` (chapter 6.1). | -`TranslationStore`, `Renderer`, and `plugins.{stores,renderers}` are declared today as the shape a future pluggable version will use, but nothing in v1 reads or calls them yet (tracked in chapter 13). +`plugins.stores` is wired as of chapter 13; `Renderer`/`plugins.renderers` are still declared only as the shape a future pluggable version will use, with nothing in v1 reading or calling them yet. ## 12. Open questions (to be settled as implementation proceeds) @@ -650,5 +650,6 @@ None at this time. Anything that comes up during implementation will be appended - **A per-command `--locale` flag**: done, for `build`/`check`/`translate`/`extract` — each accepts `--locale ` to restrict a run to one locale instead of every locale in `locales.list`, via a shared `resolveTargetLocales` helper that also rejects a locale not in `locales.list` with 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 typegen` doesn'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`](../extensions/vscode) — in progress. Syntax highlighting for `:::kiritan{...}`/`::kiritan{...}` blocks (a declarative TextMate grammar injected into Markdown, no compiled extension code) is done. Published as `otoneko1102.kiritan` (a VS Code extension identifier can't contain a `/`, ruling out `@kiritan/vscode` as originally envisioned; its `package.json` `"name"` is the plain `"kiritan"`). Since that collides with the CLI package's own npm name, it lives under `extensions/` rather than `packages/` and so is never picked up by the root `"workspaces": ["packages/*"]` glob — its build/test tooling lives in the root `package.json`'s `devDependencies` instead (chapter 2.1). Highlighting for `%{name}` (and its `\%{name}` escape), folding for `:::kiritan` blocks (colon-count matched via a small stack, so nesting other directives around a kiritan block doesn't confuse it), jump-to-definition from `:::kiritan{#}` to its entry in the sibling `..catalog.json`, undefined-`%{name}`-variable warnings, and inline `missing`/`stale`/`machine` indicators are all done — the last two settled the "bigger design question" the others were left waiting on: rather than requiring `kiritan`'s internals in-process (real crash/version-skew risk from a broken or mismatched project install), `diagnostics.cjs` spawns the workspace's own locally-installed `kiritan check --json` as a child process, the same approach ESLint/Prettier's editor integrations use for their own local installs. `npx --no-install` means a project that doesn't depend on `kiritan` at all is silently skipped rather than triggering a surprise network install. `kiritan check` gained a `--json` flag and `CheckIssue.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, matching `interpolation.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 custom `interpolation.delimiters` still gets everything else. It also registers `*.kiritanconfig` as its own language, delegating highlighting to `source.js` via a TextMate `include` and reusing JavaScript's bracket/comment/indent rules via its own `language-configuration.json` — this is why config files are named `*.kiritanconfig` rather than `.kiritan.mjs` (chapter 3.1): a file icon theme's own rules always beat a language's fallback icon, so keeping a real `.mjs` extension 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 actual `javascript`/`typescript` language ids, and giving `*.kiritanconfig` the real `javascript` id would let vscode-icons' own language-based icon rule override the custom one. `extension.cjs` bridges this: it mirrors a `*.kiritanconfig` document's content into an in-memory `javascript` document (a `TextDocumentContentProvider`-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`](../extensions/vim) — highlighting done, everything past that still open. 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.vim` highlights `:::kiritan{...}`/`::kiritan{...}` directives and `%{name}` interpolation by layering onto the built-in `markdown` syntax, the Vimscript equivalent of the VS Code extension's TextMate grammar injection, and `ftdetect/kiritanconfig.vim` assigns the real `javascript` filetype to `*.kiritanconfig` files directly — no need for VS Code's `kiritanconfig`-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 headless `vim -u NONE` process (`synID()`/`synIDattr()` at specific positions), not just asserted against the `.vim` source, the same rigor the VS Code extension's grammar tests use — this actually caught a real gotcha along the way: Vim's `:syntax on` autocommand only ever runs `runtime! syntax/.vim` against each `'runtimepath'` entry's own `syntax/` subdirectory, never a nested `after/syntax/`, so a plugin's `after/` subdirectory has to be added to `'runtimepath'` as its *own* separate entry (which plugin managers do automatically) for `after/syntax/markdown.vim` to load at all. Folding (`after/ftplugin/markdown.vim` sets `'foldexpr'` to `autoload/kiritan.vim`'s `kiritan#FoldExpr`, precomputing every line's fold level with the same colon-count-stack algorithm as `folding-core.cjs`, cached per buffer against `b:changedtick`) and jump-to-catalog-entry (`:KiritanJumpToCatalog`, bound to nothing by default — see the plugin's README for wiring up `(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 inline `missing`/`stale`/`machine` indicators are done too, but Neovim-only (`nvim-0.10+`) — `lua/kiritan/diagnostics.lua`, auto-loaded by `plugin/kiritan.lua`, ports the VS Code extension's `diagnostics.cjs` approach exactly: shells out to the workspace's own locally-installed `kiritan check --json` via `npx --no-install` and sets real `vim.diagnostic` entries from the result. Plain Vim has nothing resembling `vim.diagnostic`/`vim.system` to port this to — and needs no explicit guard against loading it anyway, since Vim's own runtime loader only globs `plugin/*.vim`, never `.lua`, so `plugin/kiritan.lua` is simply never read under Vim in the first place (confirmed directly: adding it left Vim's own `:scriptnames` completely unaware of its existence, no error, no side effect). Verified with a real headless `nvim --clean` process the same way as the Vimscript side, which caught a real bug before it shipped: `kiritan check` exits 1 whenever any issue matches `check.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's `exec` rejects on any non-zero exit but the rejection still carries `.stdout`), was hiding in the VS Code extension's own `diagnostics.cjs` and got fixed alongside this. Releases are lighter than the other components too, since there's nothing to build: `release-vim.yml` just runs the test suite and tags the commit as `kiritan-vim@` with a `--generate-notes` GitHub Release (no attached asset). There's no `package.json` here to hold a current version to bump from, so it finds the latest existing `kiritan-vim@*` tag and reuses `npm version`'s own semver logic against a throwaway `package.json` — the same `patch`/`minor`/`major`/`prerelease` keyword or explicit-version `version` input as `release.yml`. -- **Wiring `plugins.stores`/`plugins.renderers`**: making the declared `TranslationStore`/`Renderer` interfaces (chapter 11) actually pluggable, instead of `sidecar`/`inline`/`catalog` and the Markdown renderer being hardcoded into the pipeline as they are in v1. +- **Wiring `plugins.stores`**: done. `build`/`check`/`translate`/`extract` all dispatch a source whose `strategy` matches a `plugins.stores` key to that `TranslationStore`'s `read`/`write`/`status` (chapter 4, chapter 11) instead of throwing — the two `TranslatedContent` shapes 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 into `renderForLocale`'s existing per-id fallback, so no new fallback logic was needed). Staleness is left entirely to the store's own `status()` — `check`/`translate` trust it outright rather than trying to recompute it the way the built-in `sidecar`/`catalog` formats do for themselves, since a plugin store is a black box kiritan doesn't own the internals of. `check` only calls `status()`, not `read()`, so there's no generic "machine-translated, needs review" issue for a plugin store the way `catalog`'s own `machine` flag produces one — that stays a `catalog`-specific concept for now. `translate`/`extract` both no-op for a store with no `write` (a read-only store, e.g. one backed by an external TMS kiritan can only read from). A `strategy` matching neither a built-in nor a registered store now throws in all four commands, not just `build` as before — a deliberate tightening, since a custom `strategy` typo (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`**: still not done, and deliberately scoped separately from `plugins.stores` above — the declared `Renderer` interface (`parse(sourceText): { raw: string }`, `reassemble(doc, translated: string)`) has no way to represent the mdast tree `directive/render.ts`'s `renderForLocale`/`collectCatalogSegments`/etc. actually operate on end-to-end, so it can't be wired against the real pipeline as declared. A working design needs an actual second renderer (see the next item) to validate the interface's real shape against, not just the bare `strategies: StoreStrategy[]` field it already has. - **`text`/`mdx` renderers and front-matter protection**: v1 only implements the `markdown` renderer; `.txt`/`.mdx` support and `translateFrontmatter` (chapter 6) are design-stage only. diff --git a/packages/kiritan/src/pipeline/build.test.ts b/packages/kiritan/src/pipeline/build.test.ts index 0e2930a..80b2577 100644 --- a/packages/kiritan/src/pipeline/build.test.ts +++ b/packages/kiritan/src/pipeline/build.test.ts @@ -2,9 +2,32 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import type { KiritanConfig } from "../config/types.js"; +import type { + KiritanConfig, + TranslatedContent, + TranslationStore, +} from "../config/types.js"; import { build } from "./build.js"; +/** A minimal in-memory `TranslationStore` fake, keyed by locale. */ +function createMemoryStore( + initial: Record = {} +): TranslationStore { + const data = new Map(Object.entries(initial)); + return { + id: "memory", + async read(_ctx, locale) { + return data.get(locale) ?? null; + }, + async write(_ctx, locale, content) { + data.set(locale, content); + }, + async status(_ctx, locale) { + return data.has(locale) ? "complete" : "missing"; + }, + }; +} + let cwd: string; beforeEach(async () => { @@ -223,3 +246,72 @@ describe("build (catalog strategy)", () => { expect(ja).toContain("Original text."); }); }); + +describe("build (plugins.stores)", () => { + it("renders a full-text store's translation as its own document", async () => { + await writeFile(join(cwd, "README.base.md"), "Original text.", "utf8"); + const store = createMemoryStore({ + ja: { kind: "full-text", text: "翻訳済みテキスト。" }, + }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + + const result = await build(config, { cwd }); + expect(result.written.sort()).toEqual(["README.ja.md", "README.md"]); + const ja = await readFile(join(cwd, "README.ja.md"), "utf8"); + expect(ja).toContain("翻訳済みテキスト。"); + expect(ja).not.toContain("Original text."); + }); + + it("resolves each #id from a segments store, falling back to the source text when missing", async () => { + await writeFile( + join(cwd, "README.base.md"), + [":::kiritan{#intro}", "Original text.", ":::"].join("\n"), + "utf8" + ); + const store = createMemoryStore({ + ja: { + kind: "segments", + segments: { intro: { text: "翻訳済みテキスト。" } }, + }, + }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + + await build(config, { cwd }); + const ja = await readFile(join(cwd, "README.ja.md"), "utf8"); + expect(ja).toContain("翻訳済みテキスト。"); + expect(ja).not.toContain("Original text."); + }); + + it("falls back to the source text with a marker when nothing is stored yet", async () => { + await writeFile( + join(cwd, "README.base.md"), + [":::kiritan{#intro}", "Original text.", ":::"].join("\n"), + "utf8" + ); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: createMemoryStore() } }, + }); + + await build(config, { cwd }); + const ja = await readFile(join(cwd, "README.ja.md"), "utf8"); + expect(ja).toContain("kiritan:untranslated (source: en)"); + expect(ja).toContain("Original text."); + }); + + it("throws for a strategy with no matching plugins.stores entry", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "unregistered" }], + }); + await expect(build(config, { cwd })).rejects.toThrow( + /the "unregistered" strategy isn't implemented yet/ + ); + }); +}); diff --git a/packages/kiritan/src/pipeline/build.ts b/packages/kiritan/src/pipeline/build.ts index fe4acc0..292db68 100644 --- a/packages/kiritan/src/pipeline/build.ts +++ b/packages/kiritan/src/pipeline/build.ts @@ -6,6 +6,7 @@ import type { BuildContext, KiritanConfig, SourceConfig, + StoreContext, SwitcherConfig, } from "../config/types.js"; import { resolveTargetLocales } from "../config/locale.js"; @@ -190,6 +191,69 @@ export async function build( continue; } + const store = config.plugins?.stores?.[file.source.strategy]; + if (store) { + const baseTree = ensureSwitcherMarker( + parseMarkdown(sourceText), + switcherConfig + ); + const ctx: StoreContext = { source: file.source, filePath: file.path }; + + for (const locale of targetLocales) { + const outPath = outputPathFor(locale); + + if (locale === config.locales.default) { + const rendered = renderForLocale(baseTree, { + targetLocale: locale, + defaultLocale: config.locales.default, + renderSwitcher: renderSwitcherFor(locale, outPath), + }); + await writeOutput( + cwd, + outPath, + finalizeTree(rendered, config, locale) + ); + written.push(outPath); + continue; + } + + const content = await store.read(ctx, locale); + + // A "full-text" result replaces the whole document, the same way a sidecar file's own content does — it's parsed fresh rather than layered onto the base tree. + if (content?.kind === "full-text") { + const tree = ensureSwitcherMarker( + parseMarkdown(content.text), + switcherConfig + ); + const rendered = renderForLocale(tree, { + targetLocale: locale, + defaultLocale: config.locales.default, + renderSwitcher: renderSwitcherFor(locale, outPath), + }); + await writeOutput( + cwd, + outPath, + finalizeTree(rendered, config, locale) + ); + written.push(outPath); + continue; + } + + // A "segments" result (or nothing stored yet) is treated catalog-style — renderForLocale's own per-id fallback handles a missing id or a null/undefined content. + const segments = + content?.kind === "segments" ? content.segments : undefined; + const rendered = renderForLocale(baseTree, { + targetLocale: locale, + defaultLocale: config.locales.default, + resolveCatalogText: segments ? (id) => segments[id]?.text : undefined, + renderSwitcher: renderSwitcherFor(locale, outPath), + }); + await writeOutput(cwd, outPath, finalizeTree(rendered, config, locale)); + written.push(outPath); + } + continue; + } + throw new Error( `kiritan: the "${file.source.strategy}" strategy isn't implemented yet` ); diff --git a/packages/kiritan/src/pipeline/check.test.ts b/packages/kiritan/src/pipeline/check.test.ts index caa802e..7665247 100644 --- a/packages/kiritan/src/pipeline/check.test.ts +++ b/packages/kiritan/src/pipeline/check.test.ts @@ -2,12 +2,31 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import type { KiritanConfig } from "../config/types.js"; +import type { + KiritanConfig, + StoreStatus, + TranslationStore, +} from "../config/types.js"; import { parseMarkdown, stringifyMarkdown } from "../directive/parse.js"; import { collectCatalogSegments } from "../directive/render.js"; import { hashText, withHashComment } from "../hash/index.js"; import { check, resolveInterpolationVariableNames } from "./check.js"; +/** A `TranslationStore` fake reporting a fixed status per locale (`"complete"` if unlisted). */ +function createStatusStore( + statuses: Record +): TranslationStore { + return { + id: "memory", + async read() { + return null; + }, + async status(_ctx, locale) { + return statuses[locale] ?? "complete"; + }, + }; +} + /** Matches how `checkCatalog` hashes a segment, so tests can assert against a real hash without guessing the exact stringified form. */ function catalogSegmentHash(baseMarkdown: string, id: string): string { const segments = collectCatalogSegments(parseMarkdown(baseMarkdown)); @@ -463,6 +482,66 @@ describe("check (locale option)", () => { }); }); +describe("check (plugins.stores)", () => { + it("maps missing/partial to a missing issue and stale to a stale issue", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const store = createStatusStore({ ja: "missing" }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + const result = await check(config, { cwd }); + expect(result.issues).toEqual([ + { + kind: "missing", + source: "README.base.md", + locale: "ja", + detail: 'plugin store "memory" reports no translation', + }, + ]); + expect(result.failed).toBe(true); + }); + + it("reports no issue once the store reports complete", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const store = createStatusStore({ ja: "complete" }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + const result = await check(config, { cwd }); + expect(result.issues).toEqual([]); + }); + + it("reports a stale issue when the store reports stale", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const store = createStatusStore({ ja: "stale" }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + const result = await check(config, { cwd }); + expect(result.issues).toEqual([ + { + kind: "stale", + source: "README.base.md", + locale: "ja", + detail: 'plugin store "memory" reports a stale translation', + }, + ]); + }); + + it("throws for a strategy with no matching plugins.stores entry", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "unregistered" }], + }); + await expect(check(config, { cwd })).rejects.toThrow( + /the "unregistered" strategy isn't implemented yet/ + ); + }); +}); + describe("resolveInterpolationVariableNames", () => { it("returns an empty array when no variables are configured", () => { const config = baseConfig(); diff --git a/packages/kiritan/src/pipeline/check.ts b/packages/kiritan/src/pipeline/check.ts index f5f5dae..3e1c6f6 100644 --- a/packages/kiritan/src/pipeline/check.ts +++ b/packages/kiritan/src/pipeline/check.ts @@ -1,7 +1,11 @@ import { readFile } from "node:fs/promises"; import { join } from "node:path"; import { resolveTargetLocales } from "../config/locale.js"; -import type { KiritanConfig } from "../config/types.js"; +import type { + KiritanConfig, + StoreContext, + TranslationStore, +} from "../config/types.js"; import { parseMarkdown, stringifyMarkdown } from "../directive/parse.js"; import { collectCatalogIds, @@ -178,6 +182,38 @@ async function checkCatalog( } } +/** + * A plugin store is a black box — rather than trying to recompute staleness itself the way `checkSidecar`/`checkCatalog` do for the built-in formats they own, this trusts `store.status()` outright. `"missing"`/`"partial"` both surface as a `"missing"` issue (there's no dedicated `CheckIssueKind` for "some but not all of it"); `"complete"` reports nothing. Unlike `checkCatalog`, this never reports a `"machine"` issue — reviewing machine-translated content is a `catalog`-specific concept for now, since the generic `TranslationStore` contract has no equivalent of `CatalogEntry.machine` without also calling `read()`. + */ +async function checkPluginStore( + file: DiscoveredFile, + config: KiritanConfig, + store: TranslationStore, + issues: CheckIssue[], + targetLocales: string[] +): Promise { + const ctx: StoreContext = { source: file.source, filePath: file.path }; + for (const locale of targetLocales) { + if (locale === config.locales.default) continue; + const status = await store.status(ctx, locale); + if (status === "missing" || status === "partial") { + issues.push({ + kind: "missing", + source: file.path, + locale, + detail: `plugin store "${store.id}" reports no translation`, + }); + } else if (status === "stale") { + issues.push({ + kind: "stale", + source: file.path, + locale, + detail: `plugin store "${store.id}" reports a stale translation`, + }); + } + } +} + async function checkRuntimeResources( config: KiritanConfig, cwd: string, @@ -222,6 +258,7 @@ export function resolveInterpolationVariableNames( * `kiritan check` (docs/DESIGN.md chapter 8): finds missing/stale/machine-translated content across every source, plus `i18n-key-mismatch` for every `runtime.sources` strategy (`colocated`/`split`/`centralized`/`embedded`). * Stale detection compares a hash embedded at translation time (a `` comment for `sidecar`, the catalog entry's `hash` field for `catalog`) against the source's current hash; a file/entry with no hash yet (predating this feature, or hand-authored) is never flagged. * `inline` has no stale detection yet, since there's no per-block place to embed a hash without kiritan owning the base file's translated content. + * A source whose `strategy` matches a `plugins.stores` entry is checked via that store's own `status()` instead (see `checkPluginStore`); one matching neither a built-in strategy nor a registered store throws. */ export async function check( config: KiritanConfig, @@ -252,6 +289,16 @@ export async function check( await checkCatalog(file, sourceText, config, cwd, issues, targetLocales); continue; } + + const store = config.plugins?.stores?.[file.source.strategy]; + if (store) { + await checkPluginStore(file, config, store, issues, targetLocales); + continue; + } + + throw new Error( + `kiritan: the "${file.source.strategy}" strategy isn't implemented yet` + ); } await checkRuntimeResources(config, cwd, issues, targetLocales); diff --git a/packages/kiritan/src/pipeline/extract.test.ts b/packages/kiritan/src/pipeline/extract.test.ts index e3702ba..1d72c9c 100644 --- a/packages/kiritan/src/pipeline/extract.test.ts +++ b/packages/kiritan/src/pipeline/extract.test.ts @@ -2,9 +2,38 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import type { KiritanConfig } from "../config/types.js"; +import type { + KiritanConfig, + TranslatedContent, + TranslationStore, +} from "../config/types.js"; import { extract } from "./extract.js"; +/** A minimal in-memory `TranslationStore` fake, keyed by locale. `writable: false` omits `write` entirely (a read-only store). */ +function createMemoryStore( + options: { + initial?: Record; + writable?: boolean; + } = {} +): { store: TranslationStore; data: Map } { + const data = new Map(Object.entries(options.initial ?? {})); + const store: TranslationStore = { + id: "memory", + async read(_ctx, locale) { + return data.get(locale) ?? null; + }, + async status(_ctx, locale) { + return data.has(locale) ? "complete" : "missing"; + }, + }; + if (options.writable !== false) { + store.write = async (_ctx, locale, content) => { + data.set(locale, content); + }; + } + return { store, data }; +} + let cwd: string; beforeEach(async () => { @@ -130,3 +159,120 @@ describe("extract (locale option)", () => { ); }); }); + +describe("extract (plugins.stores)", () => { + it("scaffolds an empty entry for a new id in a segments store", async () => { + await writeFile( + join(cwd, "README.base.md"), + [":::kiritan{#intro}", "hello", ":::"].join("\n"), + "utf8" + ); + const { store, data } = createMemoryStore(); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + const result = await extract(config, { cwd }); + expect(result.changes).toEqual([ + { + source: "README.base.md", + locale: "ja", + detail: 'added id "intro" via plugin store "memory"', + }, + ]); + expect(data.get("ja")).toEqual({ + kind: "segments", + segments: { intro: { text: "" } }, + }); + }); + + it("never touches an existing entry, translated or not", async () => { + await writeFile( + join(cwd, "README.base.md"), + [":::kiritan{#intro}", "hello", ":::"].join("\n"), + "utf8" + ); + const { store, data } = createMemoryStore({ + initial: { + ja: { + kind: "segments", + segments: { intro: { text: "既存の訳文", machine: true } }, + }, + }, + }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + const result = await extract(config, { cwd }); + expect(result.changes).toEqual([]); + expect(data.get("ja")).toEqual({ + kind: "segments", + segments: { intro: { text: "既存の訳文", machine: true } }, + }); + }); + + it("reports an orphaned id without removing it", async () => { + await writeFile(join(cwd, "README.base.md"), "no directives here", "utf8"); + const { store } = createMemoryStore({ + initial: { + ja: { kind: "segments", segments: { gone: { text: "古い訳文" } } }, + }, + }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + const result = await extract(config, { cwd }); + expect(result.changes).toEqual([ + { + source: "README.base.md", + locale: "ja", + detail: + 'id "gone" is orphaned (no longer in the base file) in plugin store "memory"', + }, + ]); + }); + + it("skips a full-text store — there are no catalog ids to scaffold", async () => { + await writeFile( + join(cwd, "README.base.md"), + [":::kiritan{#intro}", "hello", ":::"].join("\n"), + "utf8" + ); + const { store } = createMemoryStore({ + initial: { ja: { kind: "full-text", text: "翻訳済み" } }, + }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + const result = await extract(config, { cwd }); + expect(result.changes).toEqual([]); + }); + + it("does nothing for a read-only store (no write)", async () => { + await writeFile( + join(cwd, "README.base.md"), + [":::kiritan{#intro}", "hello", ":::"].join("\n"), + "utf8" + ); + const { store } = createMemoryStore({ writable: false }); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "memory" }], + plugins: { stores: { memory: store } }, + }); + const result = await extract(config, { cwd }); + expect(result.changes).toEqual([]); + }); + + it("throws for a strategy with no matching plugins.stores entry", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "unregistered" }], + }); + await expect(extract(config, { cwd })).rejects.toThrow( + /the "unregistered" strategy isn't implemented yet/ + ); + }); +}); diff --git a/packages/kiritan/src/pipeline/extract.ts b/packages/kiritan/src/pipeline/extract.ts index 02f93d8..09de17f 100644 --- a/packages/kiritan/src/pipeline/extract.ts +++ b/packages/kiritan/src/pipeline/extract.ts @@ -1,10 +1,17 @@ import { mkdir, readFile, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { resolveTargetLocales } from "../config/locale.js"; -import type { KiritanConfig } from "../config/types.js"; +import type { + KiritanConfig, + StoreContext, + TranslationStore, +} from "../config/types.js"; import { parseMarkdown, stringifyMarkdown } from "../directive/parse.js"; import { collectCatalogSegments } from "../directive/render.js"; -import { discoverSourceFiles } from "../discover/sources.js"; +import { + discoverSourceFiles, + type DiscoveredFile, +} from "../discover/sources.js"; import { hashText } from "../hash/index.js"; import { catalogPathFor, @@ -28,6 +35,65 @@ export interface ExtractResult { changes: ExtractChange[]; } +/** + * The `plugins.stores` equivalent of the `catalog`-strategy scaffolding above, for a `"segments"`-shaped (or empty/`null`) store — a `"full-text"` result has no catalog ids to scaffold at all, so it's skipped, the same way a `sidecar`/`inline` source is skipped above. Does nothing if the store has no `write`. + */ +async function extractPluginStore( + file: DiscoveredFile, + config: KiritanConfig, + cwd: string, + changes: ExtractChange[], + store: TranslationStore, + targetLocales: string[] +): Promise { + if (!store.write) return; + + const sourceText = await readFile(join(cwd, file.path), "utf8"); + const segments = collectCatalogSegments(parseMarkdown(sourceText)); + const ids = new Set(segments.keys()); + const ctx: StoreContext = { source: file.source, filePath: file.path }; + + for (const locale of targetLocales) { + if (locale === config.locales.default) continue; + + const existing = await store.read(ctx, locale); + if (existing?.kind === "full-text") continue; + + const segmentsMap = { + ...(existing?.kind === "segments" ? existing.segments : {}), + }; + let changed = false; + + for (const id of ids) { + if (id in segmentsMap) continue; + segmentsMap[id] = { text: "" }; + changed = true; + changes.push({ + source: file.path, + locale, + detail: `added id "${id}" via plugin store "${store.id}"`, + }); + } + + for (const id of Object.keys(segmentsMap)) { + if (!ids.has(id)) { + changes.push({ + source: file.path, + locale, + detail: `id "${id}" is orphaned (no longer in the base file) in plugin store "${store.id}"`, + }); + } + } + + if (changed) { + await store.write(ctx, locale, { + kind: "segments", + segments: segmentsMap, + }); + } + } +} + /** * `kiritan extract` (docs/DESIGN.md chapter 4.3): scaffolds each catalog-strategy source's catalog files. * Adds an empty `{ text: "" }` placeholder for every `:::kiritan{#}` not yet in the catalog, ready for a translator to fill in — existing entries (translated or not) are never touched. @@ -46,7 +112,30 @@ export async function extract( const changes: ExtractChange[] = []; for (const file of files) { - if (file.source.strategy !== "catalog") continue; + if ( + file.source.strategy === "sidecar" || + file.source.strategy === "inline" + ) { + continue; + } + + if (file.source.strategy !== "catalog") { + const store = config.plugins?.stores?.[file.source.strategy]; + if (store) { + await extractPluginStore( + file, + config, + cwd, + changes, + store, + targetLocales + ); + continue; + } + throw new Error( + `kiritan: the "${file.source.strategy}" strategy isn't implemented yet` + ); + } const sourceText = await readFile(join(cwd, file.path), "utf8"); const segments = collectCatalogSegments(parseMarkdown(sourceText)); diff --git a/packages/kiritan/src/pipeline/translate.test.ts b/packages/kiritan/src/pipeline/translate.test.ts index ac8c487..e55d15b 100644 --- a/packages/kiritan/src/pipeline/translate.test.ts +++ b/packages/kiritan/src/pipeline/translate.test.ts @@ -2,7 +2,13 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import type { KiritanConfig, TranslateMiddleware } from "../config/types.js"; +import type { + KiritanConfig, + StoreStatus, + TranslateMiddleware, + TranslatedContent, + TranslationStore, +} from "../config/types.js"; import { parseMarkdown, stringifyMarkdown } from "../directive/parse.js"; import { collectCatalogSegments } from "../directive/render.js"; import { extractHashComment, hashText } from "../hash/index.js"; @@ -28,6 +34,33 @@ afterEach(async () => { const uppercase: TranslateMiddleware = async (ctx) => ctx.text.toUpperCase(); +/** A `TranslationStore` fake backed by a plain `Map`, exposing that map so tests can inspect what got written. `writable: false` omits `write` entirely (a read-only store). */ +function createMemoryStore( + options: { + initial?: Record; + statuses?: Record; + writable?: boolean; + } = {} +): { store: TranslationStore; data: Map } { + const data = new Map(Object.entries(options.initial ?? {})); + const store: TranslationStore = { + id: "memory", + async read(_ctx, locale) { + return data.get(locale) ?? null; + }, + async status(_ctx, locale) { + if (options.statuses) return options.statuses[locale] ?? "complete"; + return data.has(locale) ? "complete" : "missing"; + }, + }; + if (options.writable !== false) { + store.write = async (_ctx, locale, content) => { + data.set(locale, content); + }; + } + return { store, data }; +} + function baseConfig(overrides: Partial = {}): KiritanConfig { return { locales: { default: "en", list: ["en", "ja"] }, @@ -249,6 +282,128 @@ describe("translate (locale option)", () => { }); }); +describe("translate (plugins.stores)", () => { + it("translates the whole document into a full-text store when nothing is stored yet", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const { store, data } = createMemoryStore(); + const config = baseConfig({ + sources: [ + { + glob: "README.base.md", + strategy: "memory", + translate: { middlewares: [uppercase] }, + }, + ], + plugins: { stores: { memory: store } }, + }); + const result = await translate(config, { cwd }); + expect(result.translated).toEqual([ + { + source: "README.base.md", + locale: "ja", + detail: 'wrote via plugin store "memory"', + }, + ]); + expect(data.get("ja")).toEqual({ + kind: "full-text", + text: "HELLO", + machine: true, + }); + }); + + it("only fills in ids missing from an existing segments store", async () => { + await writeFile( + join(cwd, "README.base.md"), + [ + ":::kiritan{#intro}", + "hello", + ":::", + ":::kiritan{#outro}", + "bye", + ":::", + ].join("\n"), + "utf8" + ); + const { store, data } = createMemoryStore({ + initial: { + ja: { + kind: "segments", + segments: { intro: { text: "既存の訳文" } }, + }, + }, + statuses: { ja: "partial" }, + }); + const config = baseConfig({ + sources: [ + { + glob: "README.base.md", + strategy: "memory", + translate: { middlewares: [uppercase] }, + }, + ], + plugins: { stores: { memory: store } }, + }); + const result = await translate(config, { cwd }); + expect(result.translated).toEqual([ + { + source: "README.base.md", + locale: "ja", + detail: 'catalog id "outro" via plugin store "memory"', + }, + ]); + const stored = data.get("ja"); + if (stored?.kind !== "segments") throw new Error("expected segments"); + expect(stored.segments.intro).toEqual({ text: "既存の訳文" }); + expect(stored.segments.outro?.text).toContain("BYE"); + expect(stored.segments.outro?.machine).toBe(true); + }); + + it("does nothing once the store reports complete", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const { store, data } = createMemoryStore({ statuses: { ja: "complete" } }); + const config = baseConfig({ + sources: [ + { + glob: "README.base.md", + strategy: "memory", + translate: { middlewares: [uppercase] }, + }, + ], + plugins: { stores: { memory: store } }, + }); + const result = await translate(config, { cwd }); + expect(result.translated).toEqual([]); + expect(data.has("ja")).toBe(false); + }); + + it("does nothing for a read-only store (no write)", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const { store } = createMemoryStore({ writable: false }); + const config = baseConfig({ + sources: [ + { + glob: "README.base.md", + strategy: "memory", + translate: { middlewares: [uppercase] }, + }, + ], + plugins: { stores: { memory: store } }, + }); + const result = await translate(config, { cwd }); + expect(result.translated).toEqual([]); + }); + + it("throws for a strategy with no matching plugins.stores entry", async () => { + await writeFile(join(cwd, "README.base.md"), "hello", "utf8"); + const config = baseConfig({ + sources: [{ glob: "README.base.md", strategy: "unregistered" }], + }); + await expect(translate(config, { cwd })).rejects.toThrow( + /the "unregistered" strategy isn't implemented yet/ + ); + }); +}); + describe("translate (inline strategy)", () => { it("throws when middlewares are configured, since inline isn't supported yet", async () => { await writeFile( diff --git a/packages/kiritan/src/pipeline/translate.ts b/packages/kiritan/src/pipeline/translate.ts index f9f565c..410f4b6 100644 --- a/packages/kiritan/src/pipeline/translate.ts +++ b/packages/kiritan/src/pipeline/translate.ts @@ -4,7 +4,9 @@ import { resolveTargetLocales } from "../config/locale.js"; import type { KiritanConfig, SourceConfig, + StoreContext, TranslateContext, + TranslationStore, } from "../config/types.js"; import { parseMarkdown, stringifyMarkdown } from "../directive/parse.js"; import { collectCatalogSegments } from "../directive/render.js"; @@ -176,6 +178,90 @@ async function translateCatalog( } } +/** + * A plugin store is a black box for staleness — rather than recomputing it, this trusts `store.status()` outright (matches `checkPluginStore` in `pipeline/check.ts`) and skips entirely once it reports `"complete"`. A `"full-text"` existing value (or nothing stored yet) is translated as one whole-document middleware call, mirroring `translateSidecar`. A `"segments"` value only has its still-empty ids filled in — per-id staleness isn't detectable through the generic `TranslationStore` contract, so a `"stale"`/`"partial"` status where every id already has text is a documented no-op. Does nothing if the store has no `write` (a read-only store, e.g. one backed by an external TMS kiritan can't push to). + */ +async function translatePluginStore( + file: DiscoveredFile, + config: KiritanConfig, + cwd: string, + translated: TranslatedEntry[], + allowedLocales: string[], + store: TranslationStore +): Promise { + const middlewares = middlewaresFor(file.source, config); + if (middlewares.length === 0) return; + if (!store.write) return; + + const sourceText = await readFile(join(cwd, file.path), "utf8"); + const ctx: StoreContext = { source: file.source, filePath: file.path }; + + for (const locale of allowedLocales) { + if (locale === config.locales.default) continue; + const status = await store.status(ctx, locale); + if (status === "complete") continue; + + const existing = await store.read(ctx, locale); + + if (existing == null || existing.kind === "full-text") { + const [result] = await runTranslateMiddlewares(middlewares, [ + { + text: sourceText, + from: config.locales.default, + to: locale, + source: file.source, + }, + ]); + if (result == null) continue; + await store.write(ctx, locale, { + kind: "full-text", + text: result, + machine: true, + }); + translated.push({ + source: file.path, + locale, + detail: `wrote via plugin store "${store.id}"`, + }); + continue; + } + + const segments = collectCatalogSegments(parseMarkdown(sourceText)); + const segmentTextFor = (id: string) => + stringifyMarkdown({ type: "root", children: segments.get(id) ?? [] }); + const idsNeedingTranslation = [...segments.keys()].filter( + (id) => !existing.segments[id]?.text + ); + if (idsNeedingTranslation.length === 0) continue; + + const contexts: TranslateContext[] = idsNeedingTranslation.map((id) => ({ + text: segmentTextFor(id), + from: config.locales.default, + to: locale, + source: file.source, + segmentId: id, + })); + const results = await runTranslateMiddlewares(middlewares, contexts); + + const merged = { ...existing.segments }; + let changed = false; + for (const [index, id] of idsNeedingTranslation.entries()) { + const result = results[index]; + if (result == null) continue; + merged[id] = { text: result, machine: true }; + changed = true; + translated.push({ + source: file.path, + locale, + detail: `catalog id "${id}" via plugin store "${store.id}"`, + }); + } + if (changed) { + await store.write(ctx, locale, { kind: "segments", segments: merged }); + } + } +} + /** * `kiritan translate` (docs/DESIGN.md chapter 7): fills in missing translations, and re-translates stale ones, via `translate.middlewares`. * A translation only counts as stale once it carries a hash (a `` comment for `sidecar`, the catalog entry's `hash` field for `catalog`) that no longer matches the current source — one written by hand, with no hash yet, is left untouched. @@ -203,14 +289,31 @@ export async function translate( await translateCatalog(file, config, cwd, translated, targetLocales); continue; } - if ( - file.source.strategy === "inline" && - middlewaresFor(file.source, config).length > 0 - ) { - throw new Error( - `kiritan: "${file.path}" configures translate middlewares, but the "inline" strategy doesn't support auto-translation yet` + if (file.source.strategy === "inline") { + if (middlewaresFor(file.source, config).length > 0) { + throw new Error( + `kiritan: "${file.path}" configures translate middlewares, but the "inline" strategy doesn't support auto-translation yet` + ); + } + continue; + } + + const store = config.plugins?.stores?.[file.source.strategy]; + if (store) { + await translatePluginStore( + file, + config, + cwd, + translated, + targetLocales, + store ); + continue; } + + throw new Error( + `kiritan: the "${file.source.strategy}" strategy isn't implemented yet` + ); } return { translated };