@shipi18n/cli 1.1.5 → 2.3.0

package/bin/shipi18n.js

@@ -1,55 +1,41 @@
 #!/usr/bin/env node
-
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { translateCommand } from '../src/commands/translate.js';
-import { keysCommand } from '../src/commands/keys.js';
-import { configCommand } from '../src/commands/config.js';
-import { initCommand } from '../src/commands/init.js';
-import { readFileSync } from 'fs';
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Read package.json for version
-const packageJson = JSON.parse(
-  readFileSync(join(__dirname, '../package.json'), 'utf8')
-);
-
-const program = new Command();
-
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { translateCommand } from '../src/commands/translate.js'
+import { checkCommand } from '../src/commands/check.js'
+import { lockCommand } from '../src/commands/lock.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'))
+
+const program = new Command()
 program
   .name('shipi18n')
-  .description('🌍 Translate your locale files with Shipi18n')
-  .version(packageJson.version, '-v, --version', 'Output the current version')
-  .addHelpText('after', `
+  .description('🌍 Open-source i18n translation — bring your own LLM key')
+  .version(pkg.version, '-v, --version')
+  .addHelpText(
+    'after',
+    `
 ${chalk.cyan('Examples:')}
-  $ shipi18n init
+  $ export ANTHROPIC_API_KEY=sk-ant-...
   $ shipi18n translate en.json --target es,fr,de
-  $ shipi18n keys list
-  $ shipi18n config set apiKey sk_live_...
-
-${chalk.cyan('Get started:')}
-  1. Run ${chalk.yellow('shipi18n init')} to detect your i18n setup
-  2. Sign up at ${chalk.underline('https://shipi18n.com')} and get your API key
-  3. Run: ${chalk.yellow('shipi18n config set apiKey YOUR_KEY')}
-  4. Translate: ${chalk.yellow('shipi18n translate en.json --target es,fr')}
-
-${chalk.gray('Documentation: https://shipi18n.com/docs/cli')}
-  `);
-
-// Add commands
-initCommand(program);
-translateCommand(program);
-keysCommand(program);
-configCommand(program);
-
-// Parse arguments
-program.parse(process.argv);
-
-// Show help if no command provided
-if (!process.argv.slice(2).length) {
-  program.outputHelp();
-}
+  $ shipi18n translate en.json -p openai --target ja --incremental
+  $ shipi18n check ./locales --source en --min-coverage 95
+  $ shipi18n lock ./locales --keys 'legal.*'   # protect hand-edited strings
+
+${chalk.cyan('Bring your own LLM:')}
+  Set ${chalk.yellow('ANTHROPIC_API_KEY')} (default) or use ${chalk.yellow('-p openai')} with ${chalk.yellow('OPENAI_API_KEY')}.
+  No Shipi18n account or hosted API — your keys, your models. Apache-2.0.
+
+${chalk.gray('https://github.com/Shipi18n/shipi18n')}
+`
+  )
+
+translateCommand(program)
+checkCommand(program)
+lockCommand(program)
+program.parse(process.argv)
+if (!process.argv.slice(2).length) program.outputHelp()

package/package.json

@@ -1,71 +1,64 @@
 {
   "name": "@shipi18n/cli",
-  "version": "1.1.5",
-  "description": "Command-line tool for translating locale files with Shipi18n",
-  "main": "src/index.js",
+  "version": "2.3.0",
+  "description": "Open-source, bring-your-own-LLM i18n translation CLI. Translate locale files with your own OpenAI/Anthropic key.",
   "type": "module",
+  "bin": {
+    "shipi18n": "./bin/shipi18n.js"
+  },
   "files": [
     "bin",
-    "src/commands",
-    "src/lib",
-    "src/utils",
-    "src/index.js",
+    "src",
+    "!src/__tests__",
+    "LICENSE",
+    "NOTICE",
     "README.md",
-    "NOTICE"
+    "CHANGELOG.md"
   ],
-  "bin": {
-    "shipi18n": "./bin/shipi18n.js"
-  },
-  "scripts": {
-    "dev": "node bin/shipi18n.js",
-    "build": "echo 'No build step needed for now'",
-    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
-    "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --watch",
-    "test:coverage": "NODE_OPTIONS='--experimental-vm-modules' jest --coverage"
+  "publishConfig": {
+    "access": "public"
   },
   "keywords": [
     "i18n",
+    "cli",
     "translation",
+    "llm",
+    "openai",
+    "anthropic",
     "localization",
-    "internationalization",
-    "locale",
-    "translate",
-    "cli",
-    "i18next",
-    "react-intl",
-    "json-translation",
-    "locale-files",
-    "multilingual",
-    "l10n",
-    "ai-translation",
-    "shipi18n"
+    "bring-your-own-key"
   ],
-  "author": "Shipi18n",
   "license": "Apache-2.0",
+  "author": "Shipi18n",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shipi18n/shipi18n.git",
+    "directory": "packages/cli"
+  },
   "dependencies": {
-    "archiver": "^7.0.1",
     "chalk": "^5.3.0",
-    "commander": "^11.1.0",
-    "dotenv": "^16.3.1",
-    "inquirer": "^9.2.12",
-    "ora": "^7.0.1",
-    "yaml": "^2.3.4"
+    "commander": "^12.0.0",
+    "ora": "^8.0.1",
+    "@shipi18n/core": "^2.3.0"
   },
-  "devDependencies": {
-    "jest": "^29.7.0"
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.30.0",
+    "openai": ">=4.0.0"
   },
-  "engines": {
-    "node": ">=18.0.0"
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    }
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Shipi18n/shipi18n-cli.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Shipi18n/shipi18n-cli/issues"
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "fast-xml-parser": "^5.10.1",
+    "jest": "^29.7.0"
   },
-  "homepage": "https://shipi18n.com",
-  "publishConfig": {
-    "access": "public"
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest --passWithNoTests"
   }
-}
+}

package/src/commands/check.js

@@ -0,0 +1,160 @@
+/**
+ * `shipi18n check` — structural QA for locale files, designed to live in CI.
+ *
+ * Deterministic and offline: no LLM, no API key, no network. Reports the
+ * failure modes machine translation actually produces — dropped placeholders,
+ * collapsed plurals, missing keys, untranslated copy — and exits non-zero so a
+ * pipeline can gate on it.
+ *
+ * Formats: plain JSON locale trees (flat `locales/<lang>.json` or nested
+ * `locales/<lang>/<ns>.json`), Flutter ARB directories, and Apple String
+ * Catalogs (`.xcstrings`). Reporters: human, json, sarif, junit.
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
+import { resolve, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import chalk from 'chalk'
+import {
+  runCheck,
+  runSemantic,
+  discoverLayout,
+  compileIgnores,
+  statsFrom,
+  aggregateLanguage,
+  SEP,
+} from '@shipi18n/core'
+import { REPORTERS } from '../reporters.js'
+import { locksFor, DEFAULT_LOCKS_PATH } from './lock.js'
+
+const pkg = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf8')
+)
+
+/* ------------------------------------------------------------------ engine */
+
+// Layout discovery and tree walking live in @shipi18n/core so the CLI and the
+// MCP validator tools cannot drift apart. Re-exported here because the CLI's
+// tests and semantic pass are written against these names.
+export { runCheck, runSemantic, discoverLayout, compileIgnores, statsFrom, aggregateLanguage, SEP }
+
+/* ---------------------------------------------------------------- verdict */
+
+/** Decide the exit code from findings and flags. Reporters never influence this. */
+export function verdict(result, { failOn = 'error', minCoverage } = {}) {
+  const failures = []
+  if (failOn === 'error' && result.totals.errors > 0) failures.push(`${result.totals.errors} error(s)`)
+  if (failOn === 'warning' && result.totals.errors + result.totals.warnings > 0)
+    failures.push(`${result.totals.errors} error(s), ${result.totals.warnings} warning(s)`)
+  if (minCoverage != null) {
+    for (const l of result.languages) {
+      if (l.stats.coverage * 100 < minCoverage)
+        failures.push(`${l.lang} coverage ${(l.stats.coverage * 100).toFixed(1)}% < ${minCoverage}%`)
+    }
+  }
+  return { ok: failures.length === 0, failures }
+}
+
+/* ---------------------------------------------------------------- command */
+
+export function checkCommand(program) {
+  program
+    .command('check [input]')
+    .description('Validate translated locale files against the source language (no LLM, no key)')
+    .option('-s, --source <language>', 'Source language', 'en')
+    .option('-r, --reporter <name>', 'Output format: human | json | sarif | junit', 'human')
+    .option('-o, --output <file>', 'Write the report to a file instead of stdout')
+    .option('--json', 'Shorthand for --reporter json')
+    .option('--ignore-keys <patterns>', "Comma-separated '*' globs of keys to silence (path or ns:path)")
+    .option('--fail-on <level>', 'Exit non-zero on: error | warning | none', 'error')
+    .option('--min-coverage <pct>', 'Fail any language below this coverage percentage', parseFloat)
+    .option('--glossary <file>', 'Glossary JSON: DNT terms + locked per-language translations (deterministic)')
+    .option('--semantic', 'Add the LLM-as-judge pass (BYO key; advisory warnings by default)')
+    .option('--semantic-fail', 'Escalate semantic findings to errors (opt-in)')
+    .option('-p, --provider <name>', 'LLM provider for --semantic: anthropic | openai', 'anthropic')
+    .option('--api-key <key>', 'LLM API key for --semantic (else provider env var)')
+    .option('--semantic-model <model>', 'Judge model override')
+    .option('--semantic-passes <n>', 'Judge passes for the majority vote', (v) => parseInt(v, 10), 3)
+    .option('--semantic-cache <file>', 'Verdict cache path', '.shipi18n/semantic-cache.json')
+    .option('--locks <file>', 'Manual-translation lock file', DEFAULT_LOCKS_PATH)
+    .option('--no-locks', 'Ignore manual-translation locks')
+    .action(async (input = './locales', opts) => {
+      let glossary
+      if (opts.glossary) {
+        try {
+          glossary = JSON.parse(readFileSync(opts.glossary, 'utf8'))
+        } catch (err) {
+          console.error(chalk.red(`Error: cannot read glossary ${opts.glossary}: ${err.message}`))
+          process.exitCode = 2
+          return
+        }
+      }
+
+      let result
+      try {
+        result = runCheck({
+          input,
+          source: opts.source,
+          ignoreKeys: opts.ignoreKeys,
+          glossary,
+          locks: locksFor(opts),
+        })
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`))
+        process.exitCode = 2
+        return
+      }
+
+      if (opts.semantic) {
+        const cachePath = resolve(opts.semanticCache)
+        let cache = {}
+        if (existsSync(cachePath)) {
+          try {
+            cache = JSON.parse(readFileSync(cachePath, 'utf8'))
+          } catch {
+            cache = {} // a corrupt cache is just a cold cache
+          }
+        }
+        try {
+          const judge = await runSemantic(result, {
+            provider: opts.provider,
+            apiKey: opts.apiKey,
+            model: opts.semanticModel,
+            passes: opts.semanticPasses,
+            glossary,
+            cache,
+            fail: Boolean(opts.semanticFail),
+          })
+          mkdirSync(dirname(cachePath), { recursive: true })
+          writeFileSync(cachePath, JSON.stringify(cache, null, 2) + '\n')
+          console.error(
+            chalk.gray(
+              `semantic: judged ${judge.judged} (${judge.cached} cached), flagged ${judge.flagged}, ` +
+                `${judge.calls} model call(s), ${judge.parseFailures} discarded pass(es)`
+            )
+          )
+        } catch (err) {
+          console.error(chalk.red(`Semantic pass failed: ${err.message}`))
+          process.exitCode = 2
+          return
+        }
+      }
+
+      const verdictResult = verdict(result, { failOn: opts.failOn, minCoverage: opts.minCoverage })
+
+      const name = opts.json ? 'json' : opts.reporter
+      const reporter = REPORTERS[name]
+      if (!reporter) {
+        console.error(chalk.red(`Error: unknown reporter '${name}' (human | json | sarif | junit)`))
+        process.exitCode = 2
+        return
+      }
+      const report = reporter(result, verdictResult, { toolVersion: pkg.version })
+      if (opts.output) {
+        writeFileSync(opts.output, report.endsWith('\n') ? report : report + '\n')
+        if (name !== 'human') console.error(chalk.gray(`report written to ${opts.output}`))
+      } else {
+        console.log(report)
+      }
+      if (!verdictResult.ok) process.exitCode = 1
+    })
+}

package/src/commands/lock.js

@@ -0,0 +1,131 @@
+/**
+ * `shipi18n lock` — mark translations as hand-edited so `check` can tell you
+ * when something overwrites them, or when their source moves underneath.
+ *
+ * Writes `.shipi18n/locks.json` (safe to commit — it is the record of which
+ * translations a human has blessed).
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import chalk from 'chalk'
+import {
+  runCheck,
+  discoverLayout,
+  compileIgnores,
+  lockId,
+  lockEntry,
+  emptyLocks,
+  normalizeLocks,
+  flatten,
+} from '@shipi18n/core'
+
+export const DEFAULT_LOCKS_PATH = '.shipi18n/locks.json'
+
+/** Tolerant read — a missing or corrupt file is simply "no locks yet". */
+export function readLocks(path) {
+  if (!existsSync(path)) return emptyLocks()
+  try {
+    return normalizeLocks(JSON.parse(readFileSync(path, 'utf8')))
+  } catch {
+    return emptyLocks()
+  }
+}
+
+export function writeLocks(path, locks) {
+  mkdirSync(dirname(resolve(path)), { recursive: true })
+  writeFileSync(resolve(path), JSON.stringify(locks, null, 2) + '\n')
+}
+
+/**
+ * Build the lock set for a tree. Only pairs that actually exist in both source
+ * and target are lockable — you cannot bless a translation that isn't there.
+ */
+export function buildLocks({ input, source = 'en', keys, existing = emptyLocks(), langs }) {
+  const isSelected = compileIgnores(keys) // same glob syntax as --ignore-keys
+  const selectAll = !keys
+  const layout = discoverLayout(input, source)
+  const locked = { ...existing.locked }
+  let added = 0
+
+  const sourceData = {}
+  for (const [ns, file] of Object.entries(layout.source)) {
+    sourceData[ns] = JSON.parse(readFileSync(file, 'utf8'))
+  }
+
+  for (const { lang, files } of layout.targets) {
+    if (langs && !langs.includes(lang)) continue
+    for (const [ns, srcObj] of Object.entries(sourceData)) {
+      const file = files[ns]
+      if (!file || !existsSync(file)) continue
+      let targetObj
+      try {
+        targetObj = JSON.parse(readFileSync(file, 'utf8'))
+      } catch {
+        continue // an unparseable file has nothing lockable in it
+      }
+      const src = flatten(srcObj)
+      const tgt = flatten(targetObj)
+      for (const [path, value] of Object.entries(src)) {
+        if (typeof value !== 'string' || typeof tgt[path] !== 'string') continue
+        if (!selectAll && !isSelected(ns, path)) continue
+        const id = lockId(lang, ns, path)
+        if (!(id in locked)) added++
+        locked[id] = lockEntry(value, tgt[path])
+      }
+    }
+  }
+  return { locks: { ...emptyLocks(), locked }, added, total: Object.keys(locked).length }
+}
+
+export function lockCommand(program) {
+  program
+    .command('lock [input]')
+    .description('Record translations as hand-edited, so check warns when they are overwritten')
+    .option('-s, --source <language>', 'Source language', 'en')
+    .option('-k, --keys <patterns>', "Only lock keys matching these '*' globs (default: all)")
+    .option('-l, --lang <languages>', 'Only lock these languages (comma-separated)')
+    .option('--locks <file>', 'Lock file path', DEFAULT_LOCKS_PATH)
+    .option('--relock', 'Update hashes for keys already locked (accept current state as blessed)')
+    .action((input = './locales', opts) => {
+      try {
+        const path = resolve(opts.locks)
+        const existing = opts.relock ? emptyLocks() : readLocks(path)
+        const langs = opts.lang ? opts.lang.split(',').map((l) => l.trim()) : undefined
+        const { locks, added, total } = buildLocks({
+          input,
+          source: opts.source,
+          keys: opts.keys,
+          existing,
+          langs,
+        })
+        writeLocks(path, locks)
+        console.log(
+          chalk.green(`✓ locked ${added} new translation(s); ${total} total in ${opts.locks}`)
+        )
+        if (!opts.keys) {
+          console.log(
+            chalk.gray('  Tip: --keys narrows this to the strings you actually hand-edited.')
+          )
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`))
+        process.exitCode = 2
+      }
+    })
+}
+
+/**
+ * Used by `check` to load locks unless disabled.
+ *
+ * Commander pairs `--no-locks` with `--locks <file>`, so the negation arrives as
+ * `opts.locks === false` rather than `opts.noLocks` — checking only the latter
+ * made --no-locks silently do nothing (caught by an end-to-end run, not by a
+ * unit test that hand-built the options object).
+ */
+export function locksFor(opts = {}) {
+  if (opts.locks === false || opts.noLocks) return undefined
+  const path = resolve(typeof opts.locks === 'string' ? opts.locks : DEFAULT_LOCKS_PATH)
+  if (!existsSync(path)) return undefined
+  const locks = readLocks(path)
+  return Object.keys(locks.locked).length ? locks : undefined
+}