Skip to content

feat(kiritan): wire up plugins.stores for custom TranslationStore strategies - #43

Merged
otnc merged 1 commit into
mainfrom
feat/kiritan-plugin-stores
Sep 14, 2026
Merged

otnc merged 1 commit into
mainfrom
feat/kiritan-plugin-stores

Conversation

@otnc

@otnc otnc commented Sep 14, 2026

Copy link
Copy Markdown
Owner

Summary

  • Implements the plugins.stores half of docs/DESIGN.md chapter 13's "wiring plugins.stores/plugins.renderers" roadmap item. plugins.renderers stays unwired — see below for why, and the updated chapter 11/13 explanation in base/DESIGN.base.md.
  • build/check/translate/extract now dispatch a source whose strategy matches a config.plugins.stores key to that TranslationStore's read/write/status, instead of build throwing and check/translate/extract silently doing nothing (today's behavior for any strategy string outside sidecar/inline/catalog).
  • The two TranslatedContent shapes ("full-text", "segments") turned out to generalize the built-ins cleanly: a "full-text" result is treated sidecar-style, a "segments" result (or nothing stored yet) catalog-style — fed straight into renderForLocale's existing per-id fallback, so no new fallback logic was needed anywhere.
  • 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 (they own their own file format; a plugin store is a black box). check only calls status(), not read(), so there's no generic "machine-translated, needs review" issue for a plugin store — that stays a catalog-specific concept for now.
  • translate/extract both no-op for a store with no write (a legitimately read-only store, e.g. one backed by an external TMS kiritan can only pull 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 ("catalogg") was always a mistake with no legitimate use, and there's now an actual registration mechanism to check it against.
  • Why not plugins.renderers too: investigated first — the declared Renderer interface (parse(sourceText): { raw: string }, reassemble(doc, translated: string)) can't represent the mdast tree directive/render.ts's renderForLocale/collectCatalogSegments/etc. actually operate on end-to-end. Wiring it as declared would mean building against an interface shape that doesn't fit the real pipeline; a working design needs an actual second renderer (text/mdx, a separate not-yet-started roadmap item) to validate the interface's real shape against first.

Test plan

  • npm run ci (prettier + eslint)
  • npm run typecheck
  • npm run test (19 new tests across all four pipeline files: full-text/segments content, missing/partial/stale/complete status() mapping, a read-only store, and the new unrecognized-strategy error — full existing suite passes unchanged, confirming no regression to sidecar/inline/catalog)
  • npm run docs:build / npm run docs:check
  • fix-unnatural-line-breaks lint on every edited file
  • Manual end-to-end verification: built the CLI, wrote a real .kiritanconfig in a scratch project registering a disk-JSON-backed plugins.stores entry (a genuinely different storage format from the built-in catalog JSON, to prove the abstraction), and ran the full check → extract → check → translate → check → build round trip across separate CLI invocations, confirming the dispatch and persistence actually work outside the unit tests too. Also confirmed the unrecognized-strategy error via the real CLI.

…ategies

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.
@otnc
otnc merged commit ea753ab into main Sep 14, 2026
4 checks passed
@otnc
otnc deleted the feat/kiritan-plugin-stores branch September 14, 2026 14:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant