@x18n/cli 0.0.8 → 0.0.9

package/dist/cli.mjs

@@ -15,7 +15,7 @@ import { existsSync } from "node:fs";
 import { namespaceFromPath } from "@x18n/builtins/finders";
 import { parse, stringify } from "yaml";
 //#region package.json
-var version = "0.0.8";
+var version = "0.0.9";
 //#endregion
 //#region src/commands/change.ts
 async function project(options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/cli",
   "type": "module",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "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.8",
-    "@x18n/core": "0.0.8",
-    "@x18n/node": "0.0.8",
-    "@x18n/ui": "0.0.8",
+    "@x18n/builtins": "0.0.9",
+    "@x18n/core": "0.0.9",
+    "@x18n/node": "0.0.9",
+    "@x18n/ui": "0.0.9",
     "cac": "^7.1.0",
     "devframe": "^1.2.6",
     "nostics": "^1.3.0",

package/skills/x18n/SKILL.md

@@ -1,188 +0,0 @@
----
-name: x18n
-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
-
-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
-
-Batch the questions into one message. Routine work needs no question: adding a key you use, translating a missing message, fixing a placeholder.
-
-## Rules
-
-- 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": 2, "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).
-
-## Avoid composed keys
-
-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>`.
-
-## 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
-
-### Add a key while coding
-
-```sh
-x18n get settings.title --json
-x18n set settings.title --value "Settings" --json
-x18n keys --missing de --json --limit 50
-```
-
-`x18n set` without `--locale` writes the source locale. Then use the key in code, for example `t('settings.title')`.
-
-### Translate missing messages
-
-```sh
-x18n prompt translate --to de --limit 50
-```
-
-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,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>`.
-
-### Review translations
-
-```sh
-x18n prompt review --locale de --limit 50
-```
-
-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
-```
-
-Show the user the unused keys and delete only the ones they confirm: `x18n delete old.key --json`.
-
-### Rename keys
-
-```sh
-x18n rename home.title home.heading --dry-run --json
-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 onto an existing key is refused (exit code 1).
-
-### Extract hard-coded strings
-
-```sh
-x18n extract --list --json
-x18n extract --plan extract-plan.json
-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:
-
-- `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
-
-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 (a monorepo), pass `--project <name>` to write commands.

package/skills/x18n-check/SKILL.md

@@ -1,46 +0,0 @@
----
-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

@@ -1,27 +0,0 @@
----
-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.

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

@@ -1,49 +0,0 @@
-# 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>.