localship 0.2.0 → 0.3.0

package/dist/cli.js

@@ -30,13 +30,36 @@ import {
   submit,
   translateProject,
   validateProject
-} from "./chunk-QS3UG3KI.js";
+} from "./chunk-GNL5EFNP.js";
 
 // src/cli/main.ts
 import path from "path";
 import { createInterface } from "readline/promises";
 import { Command, InvalidArgumentError } from "commander";
-var VERSION = true ? "0.2.0" : "dev";
+
+// src/cli/cancellation.ts
+async function withCliCancellation(run) {
+  const controller = new AbortController();
+  const interrupt = () => {
+    process.exitCode = 130;
+    controller.abort();
+  };
+  const terminate = () => {
+    process.exitCode = 143;
+    controller.abort();
+  };
+  process.on("SIGINT", interrupt);
+  process.on("SIGTERM", terminate);
+  try {
+    return await run(controller.signal);
+  } finally {
+    process.off("SIGINT", interrupt);
+    process.off("SIGTERM", terminate);
+  }
+}
+
+// src/cli/main.ts
+var VERSION = true ? "0.3.0" : "dev";
 var program = new Command().name("localship").description("Local-first, agent-native localization for apps").version(VERSION).option("-c, --config <file>", "path to the config (default: the nearest .localship/config.yaml)").option("-C, --cwd <dir>", "directory to run in", process.cwd());
 var globals = () => program.opts();
 var locales = (v) => v.split(",").map((s) => s.trim()).filter(Boolean);
@@ -74,21 +97,24 @@ program.command("status").description("Translation progress per locale").option(
     for (const n of codeText) console.log(`\u25B2 ${n.target}: ${n.message}`);
   }
 });
-program.command("validate").description("Check source strings and translations; exits 1 on errors").option("-l, --locale <list>", "comma-separated locales", locales).option("--strict", "untranslated strings and missing locales are errors").option("--json", "machine-readable output").action(async (opts) => {
-  const project = await openProject(nodeFs, globals());
-  const issues = validateProject(project, {
-    locales: opts.locale,
-    strict: opts.strict,
-    usages: await buildUsageIndex(project)
-  });
-  const errors = issues.filter((i) => i.severity === "error").length;
-  if (opts.json) {
-    console.log(JSON.stringify({ ok: errors === 0, issues }, null, 2));
-  } else {
-    printIssues(issues);
+program.command("validate").description("Check source strings and translations; exits 1 on errors").option("-l, --locale <list>", "comma-separated locales", locales).option("--strict", "missing translations, Android defaults and unsupported content are errors").option("--require-approved", "require current, approved translations (implies --strict)").option("--json", "machine-readable output").action(
+  async (opts) => {
+    const project = await openProject(nodeFs, globals());
+    const issues = validateProject(project, {
+      locales: opts.locale,
+      strict: opts.strict,
+      requireApproved: opts.requireApproved,
+      usages: await buildUsageIndex(project)
+    });
+    const errors = issues.filter((i) => i.severity === "error").length;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: errors === 0, issues }, null, 2));
+    } else {
+      printIssues(issues);
+    }
+    process.exitCode = errors > 0 ? 1 : 0;
   }
-  process.exitCode = errors > 0 ? 1 : 0;
-});
+);
 program.command("detect").description("Find the translation files in this repo (writes nothing)").option("--json", "machine-readable output").action(async (opts) => {
   const result = await detect(nodeFs, globals().cwd);
   if (opts.json) {
@@ -109,9 +135,7 @@ program.command("plan").description("What it takes to translate this app: findin
   if (opts.json) console.log(JSON.stringify(p, null, 2));
   else printPlan(p);
 });
-program.command("start").description(
-  "Set up and translate in one go: config, default context, then translation with --model"
-).argument("<languages...>", "languages to translate into, as codes or names").option(
+program.command("start").description("Set up the config for these languages, then translate with --model if given").argument("<languages...>", "languages to translate into, as codes or names").option(
   "-m, --model <provider:model>",
   "translate with this model right away (default: models in the config)"
 ).option("--json", "machine-readable output").action(async (languages, opts) => {
@@ -120,25 +144,22 @@ program.command("start").description(
   const setup = await start(nodeFs, g.cwd, { locales: locales2 });
   const project = await openProject(nodeFs, g);
   const canTranslate = !!(opts.model ?? project.config.models?.default);
-  const translated = canTranslate && setup.warnings.length === 0 ? await translateProject(project, {
-    locales: setup.addedLocales.length ? setup.addedLocales : void 0,
-    model: opts.model,
-    log: (line) => console.error(line)
-  }) : void 0;
+  const translated = canTranslate ? await withCliCancellation(
+    (signal) => translateProject(project, {
+      signal,
+      locales: setup.addedLocales.length ? setup.addedLocales : void 0,
+      model: opts.model,
+      log: (line) => console.error(line)
+    })
+  ) : void 0;
   if (opts.json) {
     console.log(JSON.stringify({ setup, translated }, null, 2));
     return;
   }
   console.log(setup.createdConfig ? `Set up ${setup.config}.` : `Using ${setup.config}.`);
   if (setup.addedLocales.length) console.log(`Languages added: ${setup.addedLocales.join(", ")}`);
-  if (setup.wrote.length)
-    console.log(`Context written: ${setup.wrote.join(", ")} (edit them any time)`);
   for (const w of setup.warnings) console.log(`\u25B2 ${w}`);
-  if (setup.warnings.length) {
-    console.log(
-      "Next: move the text into resources (the localship-extract skill), then translate."
-    );
-  } else if (translated) {
+  if (translated) {
     console.log(`${translated.translated} strings translated as drafts.`);
     for (const f of translated.failed)
       console.log(`  \u2716 ${f.locale} ${f.key}: ${f.errors.join("; ")}`);
@@ -261,20 +282,25 @@ program.command("prune").description("Remove translations of strings that were d
   }
   for (const f of result.files) console.log(`  ${f}`);
 });
-program.command("translate").description("Translate missing and stale strings with a model API, as drafts").option("-l, --locale <list>", "comma-separated locales", locales).option("-t, --target <list>", "only these target ids", list).option("-k, --keys <list>", "only these keys", list).option("--states <list>", "which entries (default: missing,stale)", states).option("-m, --model <provider:model>", "model for every locale (default: models in the config)").option("-n, --batch-size <n>", "strings per model call", count, 30).option("-p, --parallel <n>", "model calls at once", count, 4).option("--force", "replace hand edits and reviewed or approved translations").option("--json", "machine-readable output").action(
+program.command("translate").description("Translate missing and stale strings with a model API, as drafts").option("-l, --locale <list>", "comma-separated locales", locales).option("-t, --target <list>", "only these target ids", list).option("-k, --keys <list>", "only these keys", list).option("--states <list>", "which entries (default: missing,stale)", states).option("-m, --model <provider:model>", "model for every locale (default: models in the config)").option("-n, --batch-size <n>", "strings per model call", count, 30).option("-p, --parallel <n>", "model calls at once", count, 4).option("--max-prompt-bytes <n>", "maximum UTF-8 bytes of system and user prompt", count, 48e3).option("--timeout-ms <n>", "deadline per model request, including response body", count, 12e4).option("--force", "replace hand edits and reviewed or approved translations").option("--json", "machine-readable output").action(
   async (opts) => {
     const project = await openProject(nodeFs, globals());
-    const result = await translateProject(project, {
-      locales: opts.locale,
-      targets: opts.target,
-      keys: opts.keys,
-      states: opts.states,
-      model: opts.model,
-      batchSize: opts.batchSize,
-      concurrency: opts.parallel,
-      force: opts.force,
-      log: (line) => console.error(line)
-    });
+    const result = await withCliCancellation(
+      (signal) => translateProject(project, {
+        signal,
+        maxPromptBytes: opts.maxPromptBytes,
+        timeoutMs: opts.timeoutMs,
+        locales: opts.locale,
+        targets: opts.target,
+        keys: opts.keys,
+        states: opts.states,
+        model: opts.model,
+        batchSize: opts.batchSize,
+        concurrency: opts.parallel,
+        force: opts.force,
+        log: (line) => console.error(line)
+      })
+    );
     if (opts.json) {
       console.log(JSON.stringify(result, null, 2));
     } else {
@@ -296,7 +322,7 @@ program.command("translate").description("Translate missing and stale strings wi
   }
 );
 program.command("mcp").description("Run the MCP server over stdio, for Claude, Cursor, Codex and other MCP clients").action(async () => {
-  const { runServer } = await import("./server-T6GQ6CV5.js");
+  const { runServer } = await import("./server-5AITZXZV.js");
   const explicit = program.getOptionValueSource("cwd") !== "default";
   const cwd = explicit ? globals().cwd : process.env.CLAUDE_PROJECT_DIR ?? globals().cwd;
   await runServer({ cwd, version: VERSION });
@@ -333,7 +359,7 @@ program.command("init").description("Detect translation files and write .localsh
 program.parseAsync().catch((e) => {
   if (e instanceof UserError) {
     console.error(e.message);
-    process.exitCode = 2;
+    process.exitCode ??= 2;
     return;
   }
   throw e;

package/dist/{server-T6GQ6CV5.js → server-5AITZXZV.js}

@@ -25,7 +25,7 @@ import {
   translateProject,
   validateProject,
   writeContext
-} from "./chunk-QS3UG3KI.js";
+} from "./chunk-GNL5EFNP.js";
 
 // src/mcp/server.ts
 import { existsSync, readFileSync } from "fs";
@@ -44,7 +44,7 @@ function createServer(opts) {
   const server = new McpServer(
     { name: "localship", version: opts.version },
     {
-      instructions: "Localization for app projects (Android XML, gettext PO, Apple String Catalogs). For any direct request (translate the app, add a language, update translations), call localship_plan first, show the user its short plan ending with the confirm phrase, and once they say it, follow the plan's steps without more questions: localship_start, then localship_next_batch \u2192 localship_submit until nothing remains, then localship_validate. For status questions use localship_status, or localship_detect when there's no config. Never edit translation files by hand when these tools can do it."
+      instructions: "Localization for app projects (Android XML, gettext PO, Apple String Catalogs). Do what the user asked and nothing more. For a request to translate, add a language or update translations: localship_plan to see what's there, localship_start if the languages aren't set up, then localship_next_batch \u2192 localship_submit until nothing remains, then localship_validate, and report. Go by what the user means, however it's worded: wanting the app in a language ('localize the app', 'I want this in Spanish') includes moving text still in the code into string resources first (the plan's notes); keeping translations up to date doesn't; a limit they state wins. If no language was named, ask once before starting. Otherwise stop only for blockers or warnings. Don't create branches, write context files or commit unless asked. For status questions use localship_status, or localship_detect when there's no config. Never edit translation files by hand when these tools can do it."
     }
   );
   const dir = (cwd) => path.resolve(opts.cwd, cwd ?? ".");
@@ -53,9 +53,9 @@ function createServer(opts) {
     name,
     { description, inputSchema: shape, annotations },
     // biome-ignore lint/suspicious/noExplicitAny: the SDK's callback type is generic over the shape.
-    (async (args) => {
+    (async (args, extra) => {
       try {
-        const out = await run(args);
+        const out = await run(args, extra.signal);
         return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
       } catch (e) {
         if (!(e instanceof UserError)) throw e;
@@ -65,7 +65,7 @@ function createServer(opts) {
   );
   tool(
     "localship_plan",
-    'Call this first for any direct request: "translate this app to Hindi", "add French", "update the translations". It looks at the project and returns a ready plan: what it found, blockers with their fix, how many strings, the defaults it chose (voice per language, names kept as written), the steps, and the confirm phrase. Show the user a short version (what it found, the steps, the defaults they can change) and end with: Say "<confirm>" to go. Once they say it, follow the steps in order without asking more questions. If confirm is empty, explain the blocker instead.',
+    "Read-only look at a request (translate the app, add a language, update translations): the files, strings to translate per language, blockers, warnings (another tool manages translations: ask before writing), notes (text still in the code: move it first when the user wants the app in a language, otherwise just mention it), and what translators go by (voice per language, names kept). No confirmation needed: carry on with what the user asked unless there are blockers or warnings.",
     {
       cwd: cwdArg,
       locales: z.array(z.string()).optional().describe("Languages the user asked for, as codes or names (hi, Hindi, pt-BR)")
@@ -75,12 +75,10 @@ function createServer(opts) {
   );
   tool(
     "localship_start",
-    "Do the setup step of a confirmed plan in one call: creates .localship/config.yaml (or adds the languages to it), and writes default voice notes and a glossary of names to keep, without overwriting existing ones. Then draft the brief if there is none, and translate.",
+    "Create .localship/config.yaml for these languages, or add them to the existing one. Writes nothing else.",
     {
       cwd: cwdArg,
-      locales: z.array(z.string()).min(1).describe("Languages, as codes or names"),
-      voice: z.record(z.string(), z.string()).optional().describe("Voice per locale, if the user changed the plan's defaults"),
-      keepAsWritten: z.array(z.string()).optional().describe("Names to keep as written, if the user changed the plan's list")
+      locales: z.array(z.string()).min(1).describe("Languages, as codes or names")
     },
     async ({ cwd, ...o }) => start(fs, dir(cwd), o)
   );
@@ -106,15 +104,23 @@ function createServer(opts) {
   );
   tool(
     "localship_validate",
-    "Deterministic checks on source strings and translations: placeholders, plural forms, escaping, markup, glossary. ok is false when there are errors.",
+    "Deterministic checks on source strings and translations: placeholders, plural forms, escaping, markup, glossary. Use requireApproved for a release check that also requires current, approved translations. ok is false when there are errors.",
     {
       cwd: cwdArg,
       locales: localesArg,
-      strict: z.boolean().optional().describe("Untranslated strings and missing locales are errors")
+      strict: z.boolean().optional().describe("Missing translations, Android defaults and unsupported content are errors"),
+      requireApproved: z.boolean().optional().describe(
+        "Require current, approved translations for every selected locale; implies strict"
+      )
     },
-    async ({ cwd, locales, strict }) => {
+    async ({ cwd, locales, strict, requireApproved }) => {
       const p = await project(cwd);
-      const issues = validateProject(p, { locales, strict, usages: await buildUsageIndex(p) });
+      const issues = validateProject(p, {
+        locales,
+        strict,
+        requireApproved,
+        usages: await buildUsageIndex(p)
+      });
       return { ok: !issues.some((i) => i.severity === "error"), issues };
     },
     { readOnlyHint: true }
@@ -266,15 +272,19 @@ ${TRANSLATION_RULES}`,
   );
   tool(
     "localship_translate",
-    "Translate everything missing with a separate model API (configured under models: in .localship/config.yaml, or pass model as provider:model). Use for large catalogs; needs the provider's API key in the environment.",
+    "Translate everything missing with a separate model API (configured under models: in .localship/config.yaml, or pass model as provider:model). Only when the user asks for it: cloud providers bill per use and need their API key in the environment.",
     {
       cwd: cwdArg,
       locales: localesArg,
       targets: targetsArg,
       keys: keysArg,
-      model: z.string().optional().describe("provider:model, e.g. anthropic:claude-sonnet-5-5")
+      model: z.string().optional().describe("provider:model, e.g. anthropic:claude-sonnet-5-5"),
+      batchSize: z.number().int().positive().optional().describe("Entries per call (default 30)"),
+      concurrency: z.number().int().positive().optional().describe("Calls at once (default 4)"),
+      maxPromptBytes: z.number().int().positive().optional().describe("UTF-8 prompt bytes (default 48000)"),
+      timeoutMs: z.number().int().positive().max(2147483647).optional().describe("Request deadline in milliseconds (default 120000)")
     },
-    async ({ cwd, targets, ...o }) => translateProject(await project(cwd), { ...o, targets })
+    async ({ cwd, targets, ...o }, signal) => translateProject(await project(cwd), { ...o, targets, signal })
   );
   for (const name of [
     "localship",
@@ -313,4 +323,4 @@ export {
   createServer,
   runServer
 };
-//# sourceMappingURL=server-T6GQ6CV5.js.map
+//# sourceMappingURL=server-5AITZXZV.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localship",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Translate your app with the AI you already use. An MCP server, agent skills and CLI that check every translation before it's written. Android, Apple String Catalogs and gettext.",
   "keywords": [
     "localization",
@@ -43,6 +43,7 @@
     "build": "tsup",
     "dev": "tsx src/cli/main.ts",
     "test": "vitest run",
+    "benchmark": "tsx benchmarks/localization.ts",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "format": "biome check --write .",

package/skills/localship/SKILL.md

@@ -1,13 +1,27 @@
 ---
 name: localship
-description: Handle any request to localize an app with Localship — "translate this app to Hindi", "add French", "localize the app", "update the translations". Shows one short plan, waits for the user to say the confirm phrase, then does everything end to end. Use this first for direct requests; the other localship-* skills are the detailed playbooks it follows.
+description: Use whenever the user wants their app in other languages, its translations updated, or its text made ready for translation, however they phrase it ("localize the app", "I want this in Spanish", "support Hindi users", "add French", "update the translations"). Works out what they mean, does it end to end and reports, stopping only when something is in the way. Use this first; the other localship-* skills are the detailed playbooks it follows.
 ---
 
-# Localize an app with Localship: plan once, then do it all
+# Localize an app with Localship
 
-The user wants their app translated with as little back-and-forth as possible. Make every
-choice that has a sensible default, show it once, and after they confirm, don't stop to ask
-again unless something is genuinely blocked.
+Do what the user asked, all of it, and nothing they didn't ask for. Don't ask for a go-ahead
+on a normal request; stop only when something is genuinely in the way.
+
+## What the user wants
+
+Go by what the user means, not the words they use. Requests come in many forms; these are
+examples, not phrases to match.
+
+| What they want | Sounds like | Do |
+|---|---|---|
+| **The app in a language**, all of it | "localize the app", "I want this in Spanish", "support Hindi users", "add French", "make it work in Arabic", "go international" | Move text still in the code into string resources (the whole app), then translate |
+| **Translations kept up to date** | "update the translations", "I changed some copy", "translate the new strings", "sync Hindi" | Translate what's missing or changed in the string resources; mention text still in the code |
+| **Text ready for translation**, nothing translated | "make the app localizable", "find hardcoded strings", "move the text into strings.xml", "prepare for translation" | Move the text only (the `localship-extract` skill) |
+
+A limit the user states wins: "just translate the strings file" or "don't touch the code" means
+translate only. If you can't tell which they mean and the plan has `notes` (text still in the
+code), ask once, together with the languages if those are missing too.
 
 ## Tools
 
@@ -15,53 +29,62 @@ Use the `localship_*` MCP tools when available. Otherwise the CLI: `localship pl
 `localship start`, `localship next-batch`, `localship submit` (install once with
 `npm install -g localship` if it's missing).
 
-## 1. Plan (one tool call, one message)
+## 1. Look
 
-Call `localship_plan` with the languages from the request, as names or codes
-(`["Hindi"]`, `["hi", "ar"]`). Then reply with a short message, at most about 10 lines:
+Call `localship_plan` with the languages from the request, as names or
+codes (`["Hindi"]`, `["hi", "ar"]`). It writes nothing.
 
-- **What I found:** the files, how many strings, and anything in the way (the plan's `blockers`).
-  If the plan has `warnings` (another tool, like Crowdin or an over-the-air SDK, already manages
-  translations), say so plainly and ask whether to go ahead anyway.
-- **What I'll do:** the plan's `steps`, briefly.
-- **Defaults:** voice per language and names kept as written (the plan's `defaults`). Say
-  they can change any of them in their reply.
-- End with: **Say "<confirm>" to go.** (Use the plan's `confirm` phrase exactly.)
+If no language was named, ask which ones now, once, before any work, so the rest runs without
+stopping. Otherwise stop and ask only when:
+- **`blockers`**: a format Localship can't translate, or an empty String Catalog. "No
+  translation files" blocks keeping translations up to date, but not wanting the app in a
+  language: moving the text creates them. Say what's in the way and what would get past it.
+- **`warnings`**: another tool (Crowdin, an over-the-air SDK…) already manages translations.
+  Writing files could clash with it; ask whether to go ahead.
 
-If `confirm` is empty, explain the blocker plainly instead (for example, an unsupported
-format) and stop. If the request names no language, ask which ones in the same message.
+Otherwise carry on, and tell the user in one line what you're about to do, e.g. "Moving about
+300 pieces of text into string resources, then translating into Hindi." When only updating
+translations, mention the plan's `notes` (text still in the code) in that line instead: those
+strings won't be translated unless the user asks you to move them.
 
-Check `git status` before planning. If there are uncommitted changes, mention it in the plan:
-the user should be able to tell your changes from theirs.
+## 2. Do it
 
-## 2. Do it (after they say the confirm phrase)
+1. **Move the text** (when they want the app in a language and the plan has `notes` or no
+   translation files): follow the `localship-extract` skill for the whole app, building as you go, with a
+   short progress update after each part. Then run `localship_plan` again for the new counts.
+2. **Set up:** if the languages aren't configured yet, `localship_start` with them. It writes
+   only the config.
+3. **Translate:** follow the `localship-translate` skill's loop (`localship_next_batch` →
+   translate → `localship_submit`, fix rejections) until `remaining` is 0 for every language.
+4. **Check:** `localship_validate` must show no errors.
 
-Follow the plan's steps in order without asking more questions. Apply any defaults they changed.
+## 3. Report
 
-1. **Blockers first.** For `mostly-hardcoded`: create a branch (`localization`), then follow the
-   `localship-extract` skill to move the text into resources, building as you go. For a large
-   app, do it feature by feature, and give a one-line progress update after each.
-2. **Set up:** `localship_start` with the languages (plus `voice` or `keepAsWritten` if the user
-   changed them). It writes the config, voice notes and glossary.
-3. **Brief:** if there's none, write `.localship/brief.md` (or `localship_update_context`) from
-   the README and strings: what the app does, who it's for, its tone, in a few lines.
-4. **Translate:** follow the `localship-translate` skill's loop (`localship_next_batch` →
-   translate → `localship_submit`, fix rejections) until `remaining` is 0 for every language.
-   For thousands of strings with a model configured, `localship_translate` is faster.
-5. **Check:** `localship_validate` must show no errors.
-6. **Report** in a few lines: strings translated per language, anything held for review or
-   failed, the brief and glossary you wrote (so they can adjust them), and the next step:
-   review the drafts (the `localship-review` skill), then approve.
+In a few lines:
+- text moved into resources, and any naming convention you had to pick;
+- strings translated per language, and anything that failed or was held for review;
+- what translators went by: each language's voice (the project's, or the usual convention the
+  batch gave as `defaultVoice`, e.g. "addressed the user as आप") and names kept as written, so
+  the user can correct them;
+- text still in the code that wasn't moved (when only updating translations);
+- next step: review the drafts (the `localship-review` skill), then approve.
+
+If the user asks for something different (another formality, a brief, a glossary term), write it
+with `localship_update_context` or the files in `.localship/`, and redo what it affects.
+
+## Only when the user asks
 
-Stop and ask only if something blocks progress: the build breaks during extraction and the
-fix isn't obvious, a tool keeps failing, or a choice would change the app's behavior.
+- moving hardcoded text into resources, unless they want the app in a language;
+- creating a branch, committing or pushing;
+- writing a brief, voice notes or glossary;
+- translating through a model API (`localship_translate`): cloud providers bill per use;
+- approving drafts, pruning, removing or `--force` (these change or delete people's work).
 
 ## Other requests
 
-- **"Add <language>":** same flow; the plan shows only the new language's work.
-- **"Update the translations" / copy changed:** same flow; the plan counts missing and stale
-  strings. Hand-edited translations are held for review, never replaced.
-- **"What's the status?":** `localship_status` (or `localship_detect` without a config). No plan needed.
-- **"Review" / "approve":** the `localship-review` skill.
+Again by meaning, however it's worded:
+- **Progress:** `localship_status` (or `localship_detect` without a config).
+- **Checking or approving translations:** the `localship-review` skill.
+- **Setting up Localship itself** (config, brief, voice, glossary): the `localship-setup` skill.
 
-Never approve drafts on your own, and commit nothing unless the user asks.
+Hand-edited translations are always held for review, never replaced.