Skip to Content
PhasesCLI roadmap — handoff (read this in the next session)

CLI roadmap — handoff (read this in the next session)

Single page for execution order, shared work (generate + fill), locales JSON, and CepatEdge-style identity warnings. Normative specs stay in json/README.md; this file is planning only.

1. Order of execution (locked for next work)

#TrackGoalPhase doc
1locales subcommandsFinish list; add CliJsonEnvelope + COMMANDS_WITH_JSON_OUTPUT for all four subcommands where applicable; fix --json = no stdin prompts (same rules as prompts, cli-json parity).locales.md
2generate + fill (shared)Per-target targetResults + progress summary in JSON and human final summary after each target (single or multi). Same types in core/progress — one implementation path.generate.md § Planning
3Key observations (keySites)Typed observations, scan parity, core adoption. Continues in parallel where it does not block (1)–(2).key-sites.md
4Patching / loaderAuto-patch, schema validation, user-project i18n files — after ADR 004 surface; ties to locales edit.patching/README.md, ADR 004

Web (apps/web, i18nprune.dev) can stay on its own cadence; see i18nprune.dev.md. It does not block the CLI order above.

2. Why locales is first

  • Several locales * paths do not emit a stable CliJsonEnvelope or behave correctly under --json (prompts, stdout hygiene). That breaks the same contract as validate / generate / fill.
  • locales list is still a stub — ship read-only listing first (no ADR 004).

Details and acceptance: locales.md (including § Planning — parity with generate/fill/validate).

3. generate + fill — same state, same envelope fields

  • fill reuses the translation/session pipeline with generate; any targetResults[] / per-target progress work must land in both commands.
  • Types: extend packages/cli/src/types/command/generate/json.ts and fill/json.ts (or a shared translator-session type) so targetResults rows share the same progress shape where concepts match (preserved, parity skip, forced run, optional timing).
  • Human mode: after each target finishes (one or many), emit a final summary line block for that target (aligned with core/progress), not only one summary at the very end — exact UX is in generate.md § Planning.

4. CepatEdge reference — “translation equals source” guard

Path (author’s machine): ~/Projects/CepatEdge/apps/web/scripts/locales/generate/

Behavior to port (conceptually into i18nprune generate / fill, not a line-by-line copy):

ConceptLocation (CepatEdge)Intent
Identity streakutils/jsonTree.ts — IDENTITY_STREAK_THRESHOLD, maybePauseOnIdentityStreak, onIdentityStreakPauseAfter N consecutive leaf translations where normalized output === normalized source, pause and warn the user.
User choicepromptIdentityStreakPause (prompts)Continue translating or abort (CepatEdge: IdentityAbortError — no file write).
Non-interactiveMap to --yes (auto-continue / skip prompt) or --json (no stdin: either fail with issues[] or documented auto-continue — pick one and match prompts).
Fillfill.ts uses findEnglishIdenticalPaths + paritySame family of check: English-identical paths before re-translate; i18nprune already has quality / parity concepts — unify with the new streak warning so generate and fill share one policy.

Implementation notes:

  • Reuse or align with packages/cli/src/core/languages/rtlHint.ts-style warnings (human-only vs JSON) where applicable.
  • Add stable issue codes if the envelope reports “aborted after identity streak” or “suspected bad translation run”.
  • Do not duplicate docs prose here — when shipped, update commands/generate, commands/fill, issue codes.

5. Checklist for the next implementer

  • locales: implement list; add --json + envelope for dynamic, delete, list, edit (or document subset); stdin/prompt rules — locales.md.
  • generate + fill: shared targetResults / per-target progress + human per-target summary — generate.md.
  • Identity streak / same-as-source warning: design flags (--yes, JSON behavior), then implement in shared translate path used by both commands.
  • key-sites: continue foundation work — key-sites.md.
  • Patching: after loader/ADR plan — patching/README.md.

See also

User-project i18n loader & config (extensibility)Phases (maintainer hub)