Skip to content

feat(kiritan): localize the CLI itself into English/Japanese - #42

Merged
otnc merged 2 commits into
mainfrom
feat/cli-i18n-yargs
Sep 14, 2026
Merged

otnc merged 2 commits into
mainfrom
feat/cli-i18n-yargs

Conversation

@otnc

@otnc otnc commented Sep 14, 2026

Copy link
Copy Markdown
Owner

Summary

  • Switches the CLI from citty to yargs (^17.7.3, matching @types/yargs) — citty has no hook for translating its own --help output or argument-parsing errors ("Missing required argument", "Unknown argument", etc.), which are hardcoded English strings inside the library itself. yargs ships full bundled translations for that boilerplate (.locale("ja")), which is what actually made this possible.
  • Adds a --lang <en|ja> flag to every command, picking the CLI's own display language — independent of --locale, which picks which document locale a build/check/translate/extract run acts on. Falls back to KIRITAN_LANG, then the usual POSIX locale env vars (LC_ALL/LC_MESSAGES/LANG), then en. An explicit but unsupported value (e.g. --lang fr) is reported as a normal invalid-choice error via yargs's own validation, rather than silently falling back.
  • Every command/option description and the CLI's own plain-text success/no-op output lines now go through packages/kiritan/src/cli/messages.i18n.ts via @kiritan/runtime's createT — dogfooding kiritan's own runtime i18n for the CLI's own strings, per the user's request.
  • check --json is untouched and stays machine-readable regardless of --lang (editor tooling parses it).
  • Deliberately not translated: a CheckIssue.detail or a thrown Error.message from a pipeline function (packages/kiritan/src/pipeline/*.ts) — these are library-level strings shared by the CLI and the programmatic API, and stay in English the same way any Node library's own exceptions would.
  • messages.i18n.ts is registered as 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 — verified by temporarily deleting one ja value and confirming kiritan check actually flagged it.
  • yargs is kept external in tsdown.config.ts (not bundled) — its .locale() support reads locale JSON files at runtime from a path resolved relative to its own installed package directory, which bundling would silently break.

Test plan

  • npm run ci (prettier + eslint)
  • npm run typecheck
  • npm run test (11 new tests: resolveCliLanguage's precedence rules, and CLI-level tests spawning the real yargs parser via .parseAsync() for init/build/check in both languages, plus a --json output check)
  • npm run docs:build / npm run docs:check
  • fix-unnatural-line-breaks lint on every edited/new file
  • Manual end-to-end verification: built the CLI and ran --help/subcommand --help in both languages, an unknown command, no command at all, and a bad --lang value (all correctly localized via yargs's own bundled Japanese strings); ran init/build/check --json end-to-end in a scratch project confirming translated output and unaffected JSON

…glish/Japanese

Switches the CLI from citty to yargs, since citty has no hook for
translating its own --help output or argument-parsing errors (they're
hardcoded English strings inside the library itself) while yargs ships
full bundled translations for that boilerplate via .locale("ja").

Adds a --lang <en|ja> flag (falling back to KIRITAN_LANG, then the
usual POSIX locale env vars, then "en") that picks the CLI's own
display language, independently of --locale (which picks which
document locale a run acts on). Every command/option description and
the CLI's own plain-text output lines now go through
packages/kiritan/src/cli/messages.i18n.ts via @kiritan/runtime's
createT; --json output is untouched, staying machine-readable
regardless of --lang. A CheckIssue.detail or a thrown Error.message
from a pipeline function stays in English always, the same way a
library's own exceptions would.

messages.i18n.ts is registered as a colocated runtime.sources resource
in this repo's own .kiritanconfig, so kiritan check/typegen catch a
missing en/ja pair here the same way they would for any other
project's own resources.

yargs is kept external in tsdown.config.ts rather than bundled, since
its .locale() support reads locale JSON files at runtime from a path
relative to its own installed package directory — bundling it away
would silently break that lookup.
@socket-security

socket-security Bot commented Sep 14, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Added@​types/​yargs@​17.0.351001007583100
Addedyargs@​18.1.09910010088100

View full report

@socket-security

socket-security Bot commented Sep 14, 2026 •

Copy link
Copy Markdown

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

Verified against the actual CLI code first: @types/yargs (still only
published for the v17 API) type-checks cleanly against yargs 18's
runtime API surface for everything this CLI uses, and .locale("ja")
behaves identically. Considered sade as an alternative first, but its
own "Usage"/"Options"/"Missing required argument"-equivalent strings
are hardcoded English literals with no locale hook at all, so it
couldn't have replaced yargs here in the first place.

yargs 18 dropped CJS entirely (ESM-only), unlike 17's dual-format
export map — updated the tsdown.config.ts comment explaining why
`yargs` is kept external accordingly (an externalized require("yargs")
in the unused dist/cli.cjs stub would throw if anyone ran it, but
nothing does; the real dist/cli.mjs bin entry only ever imports it).
@otnc
otnc merged commit f71be7e into main Sep 14, 2026
4 checks passed
@otnc
otnc deleted the feat/cli-i18n-yargs branch September 14, 2026 12:54
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