@x18n/cli 0.0.0 → 0.0.3

package/dist/cli.mjs

@@ -9,9 +9,10 @@ import { createInterface } from "node:readline/promises";
 import { configFileNames, findConfigFile, loadWorkspace, migrateI18nAlly } from "@x18n/node";
 import { extractItems, findCandidates, toPlanFile } from "@x18n/builtins/extractors";
 import { existsSync } from "node:fs";
+import { namespaceFromPath } from "@x18n/builtins/finders";
 import { parse, stringify } from "yaml";
 //#region package.json
-var version = "0.0.0";
+var version = "0.0.3";
 //#endregion
 //#region src/commands/change.ts
 async function project(options) {
@@ -295,9 +296,8 @@ async function status(options) {
 		out(`${loaded.name} (${displayPath(loaded.root, "")})`);
 		out(`  ${project.resources.length} resources, ${project.keys().length} keys, ${project.usages().length} usages`);
 		for (const c of project.analyze().coverage) {
-			const info = project.localeInfo(c.locale);
 			const label = `${c.locale}${c.locale === project.sourceLocale ? " (source)" : ""}`;
-			out(`  ${info.flag ?? "  "} ${label.padEnd(16)} ${String(percent(c)).padStart(5)}%  ${c.translated}/${c.total}${c.missing.length ? `, ${c.missing.length} missing` : ""}${c.empty.length ? `, ${c.empty.length} empty` : ""}`);
+			out(`  ${label.padEnd(16)} ${String(percent(c)).padStart(5)}%  ${c.translated}/${c.total}${c.missing.length ? `, ${c.missing.length} missing` : ""}${c.empty.length ? `, ${c.empty.length} empty` : ""}`);
 		}
 		out(`  ${summary.errors} errors, ${summary.warnings} warnings`);
 	}
@@ -429,7 +429,7 @@ async function locales(options) {
 		printJson("locales", { projects });
 		return;
 	}
-	for (const p of projects) for (const l of p.locales) out(`${l.flag ?? "  "} ${l.code.padEnd(10)} ${(l.displayName ?? "").padEnd(28)} ${l.resources.join(", ")}`);
+	for (const p of projects) for (const l of p.locales) out(`${l.code.padEnd(10)} ${(l.displayName ?? "").padEnd(28)} ${l.resources.join(", ")}`);
 }
 async function doctor(options) {
 	const projects = (await openWorkspace(options)).projects.map((loaded) => ({
@@ -445,7 +445,10 @@ async function doctor(options) {
 		out(`# ${e.name} (${e.root})`);
 		out(`config: ${e.configFile ?? "none (detection only)"}`);
 		out(`presets:`);
-		for (const p of e.presets) out(`  ${p.reason === "detected" || p.reason === "listed" ? "✓" : "·"} ${p.name} (${p.reason})`);
+		const applied = e.presets.filter((p) => p.reason === "detected" || p.reason === "listed");
+		for (const p of applied) out(`  ✓ ${p.name} (${p.reason})`);
+		if (applied.length === 0) out("  none");
+		if (e.presets.length > applied.length) out(`  ${e.presets.length - applied.length} others not applied (--json lists them)`);
 		out("finders:");
 		for (const f of e.finders) out(`  ${f.id}: ${f.resources.length} resources${f.resources.length ? `\n    ${f.resources.slice(0, 20).join("\n    ")}` : ""}`);
 		out("formats:");
@@ -513,6 +516,21 @@ async function schema(name, options) {
 	});
 	else out(text);
 }
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** The folders and file name that name `namespace`, in the style of `namespace.fromPath`. */
+function namespaceSpan(parts, namespace, fromPath) {
+	for (let start = 0; start < parts.length; start++) for (let end = start + 1; end <= parts.length; end++) if (namespaceFromPath(parts.slice(start, end).join("/"), fromPath) === namespace) return {
+		start,
+		end
+	};
+}
+/** The resource pattern that matches a found file: `public/locales/en/common.json` → `public/locales/{locale}/{namespaces}.{ext}`. */
+function patternOf(resource, fromPath) {
+	const parts = resource.path.replace(/\.[^./]+$/, "").split("/");
+	const span = resource.namespace === void 0 ? void 0 : namespaceSpan(parts, resource.namespace, fromPath);
+	if (span) parts.splice(span.start, span.end - span.start, "{namespaces}");
+	return `${parts.join("/")}.{ext}`.replace(new RegExp(`(^|[/._-])${escapeRegExp(resource.locale)}(?=[/._-])`), "$1{locale}");
+}
 async function init(options) {
 	const root = resolve(options.root ?? cwd());
 	const existing = findConfigFile(root);
@@ -521,9 +539,8 @@ async function init(options) {
 		cwd: root,
 		cache: false
 	})).projects[0];
-	const explanation = project.explain();
-	const detected = explanation.presets.filter((p) => p.reason === "detected" && p.name !== "general").map((p) => p.name);
-	const resources = explanation.config.resources.length > 0 ? explanation.config.resources.map((r) => r.pattern) : [...new Set(project.resources.map((r) => r.path.replace(new RegExp(`(^|/)${r.locale}(?=[./])`), "$1{locale}").replace(/\.[^.]+$/, ".{ext}")))];
+	const detected = project.explain().presets.filter((p) => p.reason === "detected" && p.name !== "general").map((p) => p.name);
+	const resources = [...new Set(project.resources.filter((r) => !r.block).map((r) => patternOf(r, project.config.namespace.fromPath)))];
 	const config = {
 		sourceLocale: project.sourceLocale,
 		resources: resources.map((pattern) => ({ pattern }))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/cli",
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.0.3",
   "description": "Manage and view i18n files of any project, for humans and agents",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -38,10 +38,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@x18n/builtins": "0.0.0",
-    "@x18n/core": "0.0.0",
-    "@x18n/node": "0.0.0",
-    "@x18n/ui": "0.0.0",
+    "@x18n/builtins": "0.0.3",
+    "@x18n/core": "0.0.3",
+    "@x18n/node": "0.0.3",
+    "@x18n/ui": "0.0.3",
     "cac": "^7.1.0",
     "devframe": "^1.2.5",
     "yaml": "^2.9.1"

package/skills/x18n/SKILL.md

@@ -1,27 +1,67 @@
 ---
 name: x18n
-description: Maintain the i18n files of a project with the x18n CLI - find missing, unused and broken keys, add and rename keys, translate missing messages, and extract hard-coded strings. Use when the task touches locale files (JSON, YAML, Vue i18n blocks) or translation keys in code, instead of editing locale files by hand.
+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.
 ---
 
 # x18n
 
-x18n reads the project's i18n setup (locale files, translate calls in code) and changes it safely. Use the `x18n` CLI instead of editing locale files directly: it keeps formatting, key style, file choice and placeholders correct, and every command has stable JSON output.
+x18n reads a project's i18n setup (locale files, translate calls in code) and changes it safely. Work through the `x18n` CLI from `@x18n/cli`: it keeps formatting, key style, file choice and placeholders correct, and every command prints a stable JSON envelope with `--json`.
+
+## Decisions belong to the user
+
+You do the legwork; the user makes the **decisions** that shape the product. Before you act on one of these, stop and ask, with your recommendation and the facts you found:
+
+- the source locale, and which locales the project supports
+- key naming and structure: namespaces, nesting, the style of new keys
+- a glossary term and its translation per locale, and terms that must stay untranslated (brand and product names)
+- 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.
 
 ## Rules
 
-- Do not edit locale files by hand. Use `x18n set`, `x18n apply`, `x18n rename` and `x18n delete`.
-- Before using a key in code, check whether it exists: `x18n get <key> --json`.
-- Never drop or rename placeholders (`{name}`, `{{count}}`, `%s`, `@:key`).
-- Pass `--json` and read the envelope `{ "x18n": 1, "command", "data", "diagnostics", "errors" }`. Never parse the human output.
-- Prefer `--dry-run` first for renames and deletes, and read the plan.
+- Change locale files through `x18n set`, `x18n apply`, `x18n rename` and `x18n delete`. The config file (`x18n.config.ts`) is the one i18n file you edit by hand.
+- Check a key before you use it in code: `x18n get <key> --json`. Reuse an existing key with the same meaning.
+- 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.
 
-## Exit codes
+## Set up x18n
 
-- `0` success
-- `1` `x18n check` found errors, or `x18n apply` rejected values
-- `2` usage or config error
-- `3` a decision is needed: re-run with `--yes` to accept the defaults
-- `4` files changed during the command: run it again
+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.
+
+Commands below use `x18n`; without the dev dependency, run them as `npx @x18n/cli <command>`.
+
+## Glossary (terms table)
+
+The `glossary` in the config is the project's terms table. Translate prompts include it, and the `glossary` check reports messages that translate a term differently.
+
+```ts
+// x18n.config.ts
+import { defineConfig } from '@x18n/core'
+
+export default defineConfig({
+  glossary: [
+    { term: 'Workspace', translations: { de: 'Arbeitsbereich', fr: 'Espace de travail' } },
+    { term: 'x18n', doNotTranslate: true },
+    { term: 'Save', translations: { de: 'Speichern' }, note: 'The button label, not "rescue"' },
+  ],
+  checks: { glossary: 'warning' },
+})
+```
+
+Maintain it while you work:
+
+- Before you translate, read the current entries: `x18n doctor --json` lists them under `config.glossary`.
+- When you meet a term that recurs across messages or has a product meaning, propose an entry to the user, with a translation for each locale.
+- Add the entries the user approves, then run `x18n check --only glossary --json` and fix the messages it reports.
 
 ## Loops
 
@@ -48,14 +88,14 @@ x18n keys --missing de --json --limit 50
 x18n prompt translate --to de --limit 50
 ```
 
-Follow the prompt: write `{ "de": { "<key>": "<translation>" } }` to a file, then:
+Follow the prompt. It holds the rules, the glossary, examples of existing translations and the code around each usage. Write `{ "de": { "<key>": "<translation>" } }` to a file, then:
 
 ```sh
 x18n apply translations.json --json
-x18n check --only placeholder-mismatch,invalid-syntax --locale de --json
+x18n check --only placeholder-mismatch,invalid-syntax,glossary --locale de --json
 ```
 
-`x18n apply` refuses values whose placeholders differ from the source and lists them in `data.rejected`; fix them and apply again. When the prompt reports more keys, continue with `x18n prompt translate --to de --cursor <nextCursor>`.
+`x18n apply` refuses values whose placeholders differ from the source and lists them in `data.rejected`. Fix them and apply again. When the prompt reports more keys, continue with `x18n prompt translate --to de --cursor <nextCursor>`.
 
 ### Review translations
 
@@ -63,16 +103,17 @@ x18n check --only placeholder-mismatch,invalid-syntax --locale de --json
 x18n prompt review --locale de --limit 50
 ```
 
-Fix wrong values with `x18n set <key> --locale de --value <text> --json` and list what you changed.
+Fix wrong values with `x18n set <key> --locale de --value <text> --json`, and list what you changed and why.
 
 ### Clean up
 
 ```sh
 x18n keys --unused --json
 x18n delete old.key --dry-run --json
-x18n delete old.key --json
 ```
 
+Show the user the unused keys and delete only the ones they confirm: `x18n delete old.key --json`.
+
 ### Rename keys
 
 ```sh
@@ -81,7 +122,7 @@ x18n rename home.title home.heading --json
 x18n rename pages screens --json
 ```
 
-A rename updates every locale and every usage in code. Renaming a parent (`pages`) moves every key under it. A rename to an existing key is refused (exit code 1).
+A rename updates every locale and every usage in code. Renaming a parent (`pages`) moves every key under it. A rename onto an existing key is refused (exit code 1).
 
 ### Extract hard-coded strings
 
@@ -91,16 +132,18 @@ x18n extract --plan extract-plan.json
 x18n extract --apply extract-plan.json --json
 ```
 
-Edit the keys in the plan file before applying it.
+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.
 
-## Paging
+## Output
 
-List commands take `--limit` and return `nextCursor`; pass it as `--cursor` to get the next page:
+Exit codes:
 
-```sh
-x18n keys --json --limit 100 --cursor 100
-```
+- `0` success
+- `1` `x18n check` found errors, or `x18n apply` rejected values
+- `2` usage or config error
+- `3` a decision is needed: re-run with `--yes` to accept the defaults
+- `4` files changed during the command: run it again
 
-## Monorepos
+List commands take `--limit` and return `nextCursor`; pass it as `--cursor` to get the next page: `x18n keys --json --limit 100 --cursor 100`.
 
-When `x18n status --json` lists several projects, pass `--project <name>` to write commands.
+When `x18n status --json` lists several projects (a monorepo), pass `--project <name>` to write commands.

package/skills/x18n/references/migrate-i18n-ally.md

@@ -0,0 +1,49 @@
+# Migrate from i18n-ally
+
+Use this when a project has i18n-ally settings: `i18n-ally.*`, legacy `vue-i18n-ally.*` or i18n-ally-next `i18n-ally-next.*` keys in `.vscode/settings.json` or a `*.code-workspace` file, or a `.vscode/i18n-ally-custom-framework.yml` (i18n-ally-next: `i18n-ally-next-custom-framework.yml`). `x18n migrate i18n-ally` converts them. It never deletes i18n-ally files.
+
+## Steps
+
+1. Record the baseline before you change anything: `npx @x18n/cli status --json` and `npx @x18n/cli keys --unused --json`. x18n already reads the i18n-ally settings without a config, so this is what the project gets today. **Done when** you have the locale list, the key count and the unused keys.
+2. Preview the migration: `x18n migrate i18n-ally --dry-run`. It prints the files it would write and notes about settings it dropped. **Done when** you have read every note.
+3. Ask the user about each **decision** the notes raise, in one message. The usual ones:
+   - `translate.*` settings (machine translation engines) are dropped. x18n writes translate prompts instead (`x18n prompt translate --to <locale>`).
+   - `languageTagSystem` is dropped: x18n uses locale codes exactly as they appear in file names.
+   - A custom framework with `monopoly: true` turns the built-in presets off (`presets: []`).
+   - Executed JS/TS locale files become read-only (`execute: true`).
+   - Reviews move to `.x18n/reviews.yml`, which x18n reads once reviews ship.
+   - The config format: `x18n.config.ts` by default, or `--format yml` / `--format json` for projects without Node.js tooling.
+4. Write the files: `x18n migrate i18n-ally --json` (add `--format yml` if the user chose YAML; `--force` replaces an existing x18n config). It writes:
+   - `x18n.config.ts` (or `.yml`, `.json`) from the project settings
+   - `x18n/custom.x18n-plugin.yml`, when there are custom regexes, a custom framework, refactor templates or `localeCountryMap` flags
+   - editor settings in `.vscode/settings.json`: `x18n.displayLocale`, `x18n.inPlace`, `x18n.annotations`, `x18n.annotationMaxLength`
+   - `.x18n/reviews.yml`, when `.vscode/i18n-ally-reviews.yml` or `.vscode/i18n-ally-next-reviews.yml` exists
+
+   **Done when** the command exits with code 0 and `data.files` lists the files above that apply.
+5. Verify: run `x18n doctor --json`, `x18n status --json` and `x18n keys --unused --json`, and compare them with the baseline of step 1. The locales and keys must match. The unused keys may shrink, because `keysInUse` and the derived-key rules now apply. **Done when** every difference is explained to the user.
+6. Clean up, after the user agrees: the command's `data.removable` lists the i18n-ally settings that x18n no longer needs. Remove them from `.vscode/settings.json`, delete the custom framework file if listed, and suggest the VS Code extension `antfu.x18n` in place of `lokalise.i18n-ally` or `lydanne.i18n-ally-next`.
+
+In VS Code, the extension offers the same migration when it finds i18n-ally settings and no x18n config: the command **x18n: Migrate from i18n-ally** previews the files and writes them on confirmation.
+
+## What maps where
+
+| i18n-ally | x18n |
+| --- | --- |
+| `localesPaths`, `pathMatcher`, `dirStructure`, `namespace` | `resources[].pattern`, with the same `{locale}`, `{namespace}`, `{namespaces}`, `{ext}` tokens |
+| `enabledFrameworks` | `presets`: every i18n-ally framework has a preset (`vue` → `vue-i18n`, `react` → `react-intl`, `ember` → `ember-intl`, `chrome-ext` → `chrome-extension`); `general` and `custom` are dropped |
+| `sourceLanguage` | `sourceLocale` |
+| `displayLanguage` | VS Code setting `x18n.displayLocale` |
+| `ignoredLocales` | `ignoreLocales` |
+| `keystyle`, `disablePathParsing` | `keyStyle` (`disablePathParsing` becomes `flat`) |
+| `defaultNamespace` | `namespace.default` |
+| `enabledParsers`, `parsers.extendFileExtensions` | `formats` |
+| `keysInUse`, `usage.derivedKeyRules`, `usage.scanningIgnore` | `usage.keysInUse`, `usage.derivedKeys`, `usage.exclude` |
+| `regex.usageMatch`, `regex.usageMatchAppend` | `scanners.regex` in the generated YAML plugin |
+| `refactor.templates` | `extract.templates` |
+| `extract.*` | `extract.*`, same meaning |
+| `sortKeys`, `sortCompare`, `indent`, `tabStyle`, `keepFulfilled` | `write.sort`, `write.indent`, `write.keepFilled` |
+| `annotations`, `annotationInPlace`, `annotationMaxLength` | VS Code settings `x18n.annotations`, `x18n.inPlace`, `x18n.annotationMaxLength` |
+| `localeCountryMap` | `localeInfo` flags in the generated YAML plugin |
+| custom framework `languageIds`, `usageMatchRegex`, `scopeRangeRegex`, `refactorTemplates`, `monopoly` | the generated YAML plugin: `scanners.regex`, `scopes.regex`, `extract.templates`; `monopoly` sets `presets: []` |
+
+The full map is on the docs page <https://x18n.antfu.dev/migration>.