@x18n/cli 0.0.3 → 0.0.5

package/dist/cli.mjs

@@ -12,7 +12,7 @@ import { existsSync } from "node:fs";
 import { namespaceFromPath } from "@x18n/builtins/finders";
 import { parse, stringify } from "yaml";
 //#region package.json
-var version = "0.0.3";
+var version = "0.0.5";
 //#endregion
 //#region src/commands/change.ts
 async function project(options) {
@@ -128,6 +128,13 @@ function reportInputs(workspace, options) {
 		};
 	});
 }
+/** History costs a git walk, so it loads only when `stale-translation` runs. */
+function needsHistory(loaded, options) {
+	const setting = loaded.project.config.checks["stale-translation"];
+	const level = typeof setting === "string" ? setting : setting?.[0];
+	const only = list(options.only);
+	return level !== "off" && (only.length === 0 || only.includes("stale-translation")) && !list(options.skip).includes("stale-translation");
+}
 async function report(workspace, options) {
 	const inputs = reportInputs(workspace, options);
 	const reporterIds = list(options.reporter);
@@ -152,6 +159,10 @@ async function report(workspace, options) {
 }
 async function check(options) {
 	const workspace = await openWorkspace(options);
+	await Promise.all(workspace.projects.filter((loaded) => needsHistory(loaded, options)).map(async (loaded) => {
+		await loaded.project.loadHistory({ watch: options.watch });
+		await loaded.host.flush();
+	}));
 	const code = await report(workspace, options);
 	if (!options.watch) return code;
 	const rerun = async () => {
@@ -492,13 +503,18 @@ async function prompt(kind, options) {
 	if (kind !== "translate" && kind !== "review") throw new X18nError("X18N0001", `unknown prompt "${kind}" (translate, review)`);
 	const locale = kind === "translate" ? options.to : options.locale ?? options.to;
 	if (!locale) throw new X18nError("X18N0001", kind === "translate" ? "pass --to <locale>" : "pass --locale <locale>");
-	const { project } = singleProject(await openWorkspace(options));
+	const { project, host } = singleProject(await openWorkspace(options));
+	if (options.stale) {
+		await project.loadHistory();
+		await host.flush();
+	}
 	const data = project.prompt(kind, locale, {
 		keys: options.keys,
 		namespace: options.namespace,
 		limit: options.limit === void 0 ? void 0 : Number(options.limit),
 		cursor: options.cursor,
-		context: options.context
+		context: options.context,
+		stale: options.stale
 	});
 	if (options.json || options.format === "json") printJson(`prompt ${kind}`, data);
 	else out(renderPrompt(data));
@@ -659,7 +675,7 @@ function createCli() {
 	cli.command("fill", "Add missing keys with empty values").option("--locale <locale>", "Only these locales (repeatable)").option("--copy-source", "Use the source value instead of an empty string").option("--dry-run", "Print the plan instead of writing").action(run("fill", fill));
 	cli.command("format", "Re-write resources with the configured sort and indent").option("--dry-run", "Print the plan instead of writing").action(run("format", format));
 	cli.command("extract [...files]", "Find hard-coded strings and turn them into keys").option("--list", "Print candidates and proposed keys").option("--plan <file>", "Write the extraction plan to a file to edit").option("--apply <file>", "Apply an (edited) extraction plan").option("--dry-run", "Print the plan instead of writing").action(run("extract", extract));
-	cli.command("prompt <kind>", "Print a prompt for an agent or LLM: `prompt translate --to <locale>` or `prompt review --locale <locale>`").option("--to <locale>", "Target locale (translate)").option("--locale <locale>", "Locale to review").option("--keys <glob>", "Only keys matching a glob").option("--namespace <ns>", "Only keys of a namespace").option("--limit <n>", "Messages per prompt (default 50)").option("--cursor <cursor>", "Continue from `nextCursor`").option("--format <format>", "markdown (default) or json").option("--no-context", "Leave out code around usages").action(run("prompt", prompt));
+	cli.command("prompt <kind>", "Print a prompt for an agent or LLM: `prompt translate --to <locale>` or `prompt review --locale <locale>`").option("--to <locale>", "Target locale (translate)").option("--locale <locale>", "Locale to review").option("--keys <glob>", "Only keys matching a glob").option("--namespace <ns>", "Only keys of a namespace").option("--limit <n>", "Messages per prompt (default 50)").option("--cursor <cursor>", "Continue from `nextCursor`").option("--format <format>", "markdown (default) or json").option("--no-context", "Leave out code around usages").option("--stale", "Also translate stale translations (needs git history)").action(run("prompt", prompt));
 	cli.command("ui", "Start the UI: browse and edit messages in the browser, with HTTP MCP at /__mcp").option("--port <port>", "Port (default: a free one from 9999)").option("--host <host>", "Bind host (default: localhost)").option("--no-open", "Do not open the browser").option("--no-auth", "Skip authentication (CI and e2e only)").action(run("ui", async (options) => (await uiCommands()).ui(options)));
 	cli.command("build", "Write a static, read-only report of the UI").option("--out-dir <dir>", "Output directory (default: .x18n/report)").action(run("build", async (options) => (await uiCommands()).build(options)));
 	cli.command("mcp", "Serve the MCP tools over stdio").action(run("mcp", async (options) => (await uiCommands()).mcp(options)));

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@x18n/cli",
   "type": "module",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Manage and view i18n files of any project, for humans and agents",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "funding": "https://github.com/sponsors/antfu",
-  "homepage": "https://github.com/antfu/x18n#readme",
+  "homepage": "https://github.com/x18n-dev/x18n#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/antfu/x18n.git",
+    "url": "git+https://github.com/x18n-dev/x18n.git",
     "directory": "packages/cli"
   },
-  "bugs": "https://github.com/antfu/x18n/issues",
+  "bugs": "https://github.com/x18n-dev/x18n/issues",
   "keywords": [
     "i18n",
     "cli",
@@ -38,12 +38,12 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@x18n/builtins": "0.0.3",
-    "@x18n/core": "0.0.3",
-    "@x18n/node": "0.0.3",
-    "@x18n/ui": "0.0.3",
+    "@x18n/builtins": "0.0.5",
+    "@x18n/core": "0.0.5",
+    "@x18n/node": "0.0.5",
+    "@x18n/ui": "0.0.5",
     "cac": "^7.1.0",
-    "devframe": "^1.2.5",
+    "devframe": "^1.2.6",
     "yaml": "^2.9.1"
   },
   "scripts": {

package/skills/x18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: x18n
-description: Set up and run x18n (`@x18n/cli`) to check and manage a project's translations. Use when the task touches locale files or translation keys - adding, renaming or deleting keys, finding missing or unused keys, translating missing messages, extracting hard-coded strings, keeping a glossary of terms - or when setting up x18n or migrating from i18n-ally.
+description: Manage a project's translations with x18n (`@x18n/cli`). Use when the task touches locale files or translation keys - adding, renaming or deleting keys, finding missing or unused keys, translating missing messages, reviewing translations, extracting hard-coded strings, keeping a glossary of terms.
 ---
 
 # x18n
@@ -17,7 +17,6 @@ You do the legwork; the user makes the **decisions** that shape the product. Bef
 - tone and formality per locale (German *du* or *Sie*, French *tu* or *vous*)
 - deleting keys that look unused, since keys built at runtime look unused too
 - renames that touch many files or move keys between namespaces
-- turning on checks, and making warnings fail CI with `--strict`
 
 Batch the questions into one message. Routine work needs no question: adding a key you use, translating a missing message, fixing a placeholder.
 
@@ -28,14 +27,51 @@ Batch the questions into one message. Routine work needs no question: adding a k
 - Keep every placeholder of the source message (`{name}`, `{{count}}`, `%{name}`, `:name`, `%s`, `@:key`).
 - Pass `--json` and read the envelope `{ "x18n": 1, "command", "data", "diagnostics", "errors" }`.
 - Run renames and deletes with `--dry-run` first, and read the plan.
+- Write every key as a full string literal. Do not build keys at runtime (see below).
 
-## Set up x18n
+## Avoid composed keys
 
-1. Run `npx @x18n/cli doctor` in the project root. Without a config, x18n uses the project's i18n-ally settings if it has any, and detects the i18n library and the locale files. Check the detected presets, the locale files and the source locale. **Done when** the doctor output names the library the project uses and lists every locale file.
-2. If the project has i18n-ally settings (`i18n-ally.*` keys in `.vscode/settings.json`), follow [references/migrate-i18n-ally.md](references/migrate-i18n-ally.md) instead of step 3.
-3. If detection is wrong or incomplete, run `x18n init` to write `x18n.config.ts`, then fix `resources`, `sourceLocale` or `presets` in it. `x18n init --format yml` writes YAML for projects without Node.js tooling. **Done when** `x18n doctor` shows the right result.
-4. Install the CLI as a dev dependency with the project's package manager (`pnpm add -D @x18n/cli`), and add a script such as `"i18n:check": "x18n check"`. Ask the user before you add it to CI.
-5. Run `x18n check --json` and report the summary to the user. **Done when** the user has the counts of errors and warnings per check, and has decided what to fix first.
+Do not build a key from parts, such as `` t(`foo.bar.${name}`) `` or `t('foo.bar.' + name)`. x18n and the compiler cannot see the full key, so:
+
+- `x18n keys --unused` reports the key as unused, and `x18n delete` can remove a message that the code needs
+- `x18n rename` does not update the usage
+- `x18n check` cannot find a missing message until the user hits it at runtime
+- translators cannot see the full key in context
+
+Write each key out in full and map the value to it:
+
+```ts
+// Avoid
+t(`status.${status}`)
+
+// Prefer: a lookup of full literal keys
+const labels = {
+  active: t('status.active'),
+  paused: t('status.paused'),
+} as const
+labels[status]
+```
+
+```ts
+// Avoid
+t(`plans.${plan}.title`)
+
+// Prefer: a switch, or a record of functions when the call must be lazy
+const planTitle = {
+  free: () => t('plans.free.title'),
+  pro: () => t('plans.pro.title'),
+}
+planTitle[plan]()
+```
+
+When the variable part is only a word inside a sentence, use a placeholder instead of a key part: `t('greeting', { name })` with the message `Hello, {name}`. When the text differs by count, use the library's plural syntax, not `t(count === 1 ? 'item.one' : 'item.many')`.
+
+If the user's code already composes keys, do not rewrite it unasked. Tell the user which keys are affected, and treat those keys as used when you clean up.
+
+## Set up and check
+
+- To set up x18n, or migrate from i18n-ally, use the `x18n-setup` skill.
+- To run `x18n check` and fix what it reports, use the `x18n-check` skill.
 
 Commands below use `x18n`; without the dev dependency, run them as `npx @x18n/cli <command>`.
 
@@ -65,13 +101,6 @@ Maintain it while you work:
 
 ## Loops
 
-### Check the project
-
-```sh
-x18n check --json
-x18n status --json
-```
-
 ### Add a key while coding
 
 ```sh
@@ -134,6 +163,16 @@ x18n extract --apply extract-plan.json --json
 
 Edit the keys in the plan file before you apply it. The proposed keys follow the project's style; ask the user when there is none yet.
 
+Tests, fixtures, mocks, stories, configs and type declarations are never scanned, in any language (`*.test.ts`, `*_test.go`, `test_*.py`, `*_spec.rb`, `*Test.java`, `vite.config.ts`, `tests/`, `spec/`, `e2e/`, ...). To keep strings that are not UI text out of the plan, drop them from the plan file, or add a control comment to the code:
+
+| Comment | Skips |
+| --- | --- |
+| `x18n-ignore-file` | the whole file, wherever the comment is |
+| `x18n-ignore-start` ... `x18n-ignore-end` | everything between them (to the end of the file when unclosed) |
+| `x18n-ignore` | strings on its line and on the next line |
+
+Use any comment syntax: `// x18n-ignore-file`, `<!-- x18n-ignore -->`. For strings that recur across files, use `extract.ignore` in the config instead.
+
 ## Output
 
 Exit codes:

package/skills/x18n-check/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: x18n-check
+description: Run `x18n check` and fix what it reports - missing keys and translations, placeholder mismatches, invalid message syntax, unused keys, glossary violations. Use when the user asks to check, lint or fix translations, when `x18n check` fails locally or in CI, or before opening a PR that touches locale files or translation keys.
+---
+
+# Check and fix translations
+
+`x18n check` reports broken, untranslated and unused messages, like `tsc --noEmit` for i18n. Run it, fix the routine problems, and bring the rest to the user. Change locale files only through the `x18n` CLI (`set`, `apply`, `rename`, `delete`), never by hand. The `x18n` skill covers those commands.
+
+If the project has no x18n setup yet, use the `x18n-setup` skill first.
+
+## Decisions belong to the user
+
+Before you act on one of these, stop and ask, with your recommendation and the facts you found. Batch the questions into one message.
+
+- deleting keys reported as unused, since keys built at runtime look unused too
+- a glossary term and its translation per locale
+- changing the severity of a check in the `checks` map of the config, such as `'unused-key': 'error'` or `glossary: 'warning'`
+- making warnings fail CI with `--strict` or `--max-warnings <n>`
+
+## Loop
+
+1. Run `x18n check --json`. Read `data.projects[].summary` for the counts and `diagnostics` for the problems. Group the diagnostics by `code` and `severity`. **Done when** you know the count per check, errors first.
+2. Fix the errors, check by check, with the table below. Re-run only that check to confirm: `x18n check --only placeholder-mismatch --json`. **Done when** the summary shows no errors, or each remaining error waits on a user decision.
+3. Fix the warnings you can fix without a decision, such as missing translations. **Done when** the remaining warnings each need a decision.
+4. Ask the user about the remaining diagnostics in one message: list them by check, with your recommendation for each. Apply what they decide.
+5. Run `x18n check --json` again and report the result. **Done when** `x18n check` exits with code 0, or every remaining diagnostic is one the user chose to keep.
+
+## Fixes per check
+
+| Check (`code`) | Fix |
+| --- | --- |
+| `missing-key` | A usage names a key the source locale lacks. If it is a typo, fix the usage to an existing key (`x18n keys` lists them). Else add it: `x18n set <key> --value <text> --json`. |
+| `missing-translation`, `empty-translation` | Translate: `x18n prompt translate --to <locale> --limit 50`, write the result to a file, then `x18n apply <file> --json`. Follow `nextCursor` when the prompt reports more keys. |
+| `placeholder-mismatch` | Rewrite the target value with every placeholder of the source: `x18n set <key> --locale <locale> --value <text> --json`. |
+| `invalid-syntax` | Fix the message syntax (ICU braces, linked messages) with `x18n set`. When a linked message does not exist, fix the link or add that key. |
+| `key-conflict` | A key is both a message and a parent, or is defined twice in one locale. Ask which one to keep, then `x18n rename` or `x18n delete` with `--dry-run` first. |
+| `unused-key` | Show the list from `x18n keys --unused --json` and delete only the keys the user confirms: `x18n delete <key> --dry-run --json`, then without `--dry-run`. Keys built at runtime go in `usage.keysInUse` in the config instead. |
+| `glossary` | Rewrite the message with the term from the glossary (`x18n doctor --json` lists it under `config.glossary`), with `x18n set`. |
+| `locale-code-conflict`, `dynamic-key`, `key-style`, `identical-to-source`, `hard-string` | Report them. Fix only when the user asks; `hard-string` is fixed with `x18n extract`, or silenced with an `x18n-ignore` control comment when the string is not UI text. |
+
+After a batch of fixes, check only what you touched: `x18n check --only placeholder-mismatch,invalid-syntax,glossary --locale de --json`.
+
+## CI
+
+`x18n check` exits with code 1 on errors, so CI fails on broken keys without more setup. Warnings do not fail it unless the project uses `--strict` or `--max-warnings <n>`. For pull request annotations, use `x18n check --reporter github --reporter pretty`. Change none of this without asking.

package/skills/x18n-setup/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: x18n-setup
+description: Set up x18n (`@x18n/cli`) in a project, or migrate it from i18n-ally. Use when a project has no x18n config yet, when x18n detects the wrong locale files or library, when the user asks to add, install or configure x18n, or when `.vscode/settings.json` has `i18n-ally.*` settings.
+---
+
+# Set up x18n
+
+x18n reads a project's i18n setup (locale files, translate calls in code) and often needs no config. Set it up by checking what it detects, and write a config only when detection needs help.
+
+## Decisions belong to the user
+
+Before you act on one of these, stop and ask, with your recommendation and the facts you found. Batch the questions into one message.
+
+- the source locale, and which locales the project supports
+- the config format: `x18n.config.ts`, or YAML for projects without Node.js tooling
+- what an i18n-ally migration drops (see the reference below)
+- adding `x18n check` to CI or to a git hook
+
+## Steps
+
+1. Run `npx @x18n/cli doctor` in the project root. Without a config, x18n uses the project's i18n-ally settings if it has any, and detects the i18n library and the locale files. Check the detected presets, the locale files and the source locale. **Done when** the doctor output names the library the project uses and lists every locale file.
+2. If the project has i18n-ally settings (`i18n-ally.*` keys in `.vscode/settings.json`), follow [references/migrate-i18n-ally.md](references/migrate-i18n-ally.md) instead of step 3.
+3. If detection is wrong or incomplete, run `x18n init` to write `x18n.config.ts`, then fix `resources`, `sourceLocale` or `presets` in it. `x18n init --format yml` writes YAML. **Done when** `x18n doctor` shows the right result.
+4. Install the CLI as a dev dependency with the project's package manager (`pnpm add -D @x18n/cli`), and add a script such as `"i18n:check": "x18n check"`. Ask the user before you add it to CI.
+5. Run `x18n check --json` and report the summary to the user: errors and warnings per check (`code` of each diagnostic) and coverage per locale. Do not fix anything in this skill. **Done when** the user has the counts and knows that the `x18n-check` skill fixes them.
+
+Without the dev dependency, run commands as `npx @x18n/cli <command>`. In a monorepo, `x18n status --json` lists every project; pass `--project <name>` to pick one.