Locale review CLI (locales:review)

apps/web/scripts/locales/review/index.ts (output routing and JSON shapes: apps/web/scripts/locales/review/outputPlan.ts)

Purpose: Analyze review metadata on non-English locale leaves (status, confidence, needsReview, source, updatedAt). It does not compare locales to en.json — use pnpm locales:validate:quality for drift and English-identical strings.

Command

From apps/web:

pnpm locales:review
pnpm locales:review -- --format summary --all
pnpm locales:review -- --lang id --format summary
pnpm locales:review -- --json --lang id,ja
pnpm locales:review -- --csv --lang id
pnpm locales:review -- --format by-source --json --lang zh-cn --top 3
pnpm locales:review -- --langs id ja ms --format by-status

--format only selects human layout: summary (default), by-status, or by-source. Do not pass json or csv there — use --json (flat or grouped with --format by-status|by-source) or --csv / --cvs (alias) for machine output.

For human formats, the CLI prints the same banner as other locale tools, then Applied options (format, scope, row filters, path-list rules). Machine outputs (--json, --csv, or grouped JSON with --format by-status|by-source + --json) print neither the banner nor Applied options on stdout — only the JSON line or CSV data rows (errors still go to stderr). --top takes priority over --full when both are set (path lists are capped at --top).

Layout (--format) vs output (--json / --csv)

Human (--format)	Role
summary (default)	Compact stats per locale (leaves, needsReview, confidence buckets, by status / by source). No path lists — use by-status, by-source, --json, or --csv for paths.
by-status	Per locale, paths grouped under each status (default 10 paths per group unless --full / --top). Add --json for JSON on stdout (byStatus).
by-source	Per locale, paths grouped under each source. Add --json for JSON on stdout (bySource).

Flag	Machine output
--json	Single line JSON on stdout (no banner). Without by-status / by-source, emits flat JSON: locales.<slug>.leaves sorted by path. With --format by-status or by-source, emits grouped JSON. Default: first 10 leaf rows per locale (or per group when grouped); --full for all rows; --top=N for a custom cap.
--csv or --cvs	CSV data rows only (no column header line, no banner). Same default cap and --full / --top rules as flat JSON. --json + --csv is an error.

JSON payloads include an applied object describing how caps were interpreted.

With pnpm, pass a double dash so flags reach the script: pnpm locales:review -- --format by-source --lang zh-cn --top 3.

Scoping

• No --lang / --langs: all non-English locales/*.json (same as scanning everything except en.json).
• --lang <code> — one or more codes comma-separated: --lang id or --lang id,zh-cn.
• --langs a b c — space-separated list (tokens until the next --flag).
• --all — explicitly include every non-English file (same list as default when no langs are given). If you pass --lang / --langs, those names win and --all is ignored.

Unknown or missing locale files exit with an error (e.g. typo in zh-cn).

List length (human by-status / by-source, and JSON groups)

• Summary does not print individual paths.
• Default: only the first 10 paths per group in by-status / by-source, with … +N more path(s) when there are more.
• --full: list all paths in each section unless --top is set.
• --top=N: hard cap on how many paths are printed per section. If both --full and --top are passed, --top wins (unlimited “full” is ignored).

Flat JSON (--json without grouped --format) and CSV use the same default cap: 10 rows per locale (sorted by path), --full for every matching row, or --top=N for a custom limit.

Filters

Flag	Effect
--needs-review / --needs-review-only	Only rows with needsReview === true.
--status=pending or --status=translated	Filter by status.
--source=<name>	e.g. google-translate, copy-en, unknown.
--min-confidence=0.5	Requires numeric confidence ≥ value.
--max-confidence=0.9	Requires numeric confidence ≤ value.
--full	List every path (with optional --top cap).
--top=N	Max paths to list when using --full, or custom limit instead of the default 10.

Legacy leaves

Until pnpm locales:sync has normalized a file, leaves may still be plain strings. Those appear as legacy status/source in reports with no confidence.

Related

• locale-leaves.md — schema for structured leaves.
• validate.md — locales:validate / quality vs en.json.