localship 0.1.0 → 0.2.0

package/README.md

@@ -6,6 +6,7 @@
 
 Free and open source · No account, no server · Any AI model · Every translation checked
 
+[![npm](https://img.shields.io/npm/v/localship?color=cb3837&logo=npm)](https://www.npmjs.com/package/localship)
 [![CI](https://github.com/jigarfumakiya/localship/actions/workflows/ci.yml/badge.svg)](https://github.com/jigarfumakiya/localship/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io)
@@ -31,29 +32,28 @@ no server, no monthly bill.
 
 - 🆓 **Free and open source.** MIT-licensed. You pay only for your own AI usage, or nothing with a
   local model.
-- 🤖 **Works with the AI you already use.** Your coding agent's own model, or Claude, GPT, Gemini,
-  OpenRouter, or a local model through Ollama.
-- 🛡️ **Catches broken translations.** Placeholders, plural forms, Android escaping and markup are
-  checked in code before anything is written. Failures go back to the AI with the reason.
+- 🤖 **Your AI, your model.** Your coding agent's own model, or Claude, GPT, Gemini, OpenRouter
+  or Ollama.
+- 🛡️ **Catches broken translations.** Placeholders, plural forms, escaping and markup are checked
+  in code before anything is written. Failures go back to the AI with the reason.
 - 🧠 **More context for the AI.** Each string comes with the code that uses it, its comment, your
   glossary and voice notes, and earlier translations of the same text.
-- 🔒 **Stays in your repo.** No server, no account, no upload. Your files, written the way Android
-  Studio and Xcode write them.
+- 🔒 **Stays in your repo.** No server, no account, no upload. Your own translation files, formatted
+  the way your tools write them.
 - 💻 **Runs anywhere.** Claude Code, Cursor, VS Code, Codex, Gemini CLI, Claude Desktop or the
   terminal, on macOS, Linux and Windows.
 
 ### 🤔 Why use Localship?
 
-Your AI can already translate a strings file if you ask. Here's what changes with Localship:
-
 | | ❌ Asking an AI directly | ✅ With Localship |
 |---|---|---|
-| Placeholders like `%1$s` | Sometimes dropped, and the app crashes on that screen | Checked before writing; sent back to fix |
-| Plural forms | Arabic often gets 2 forms instead of 6 | The right forms for every language, from Unicode CLDR |
-| Android escaping | An unescaped apostrophe breaks the build | Escaped for you |
-| Consistent terms | "Budget" translated three ways | Glossary, voice notes and earlier translations |
-| Changing copy | Everything is translated again | Only changed strings are redone, with the old and new text |
-| Your translator's fixes | Overwritten | Kept unless you ask |
+| Context | One string at a time | Code, comments, brief and glossary |
+| Placeholders | Sometimes dropped | Checked before writing |
+| Plural forms | Often incomplete | Every form each language needs |
+| Escaping and markup | Can break the build | Checked and escaped |
+| Terms and tone | Drift across strings | Same glossary and voice everywhere |
+| Changed copy | Everything redone | Only what changed |
+| Your edits | Overwritten | Kept |
 
 ## 🎬 See it in action
 
@@ -129,45 +129,44 @@ all supported.
 
 ## 🚀 Install
 
-Needs [Node.js](https://nodejs.org) 22 or newer.
-
-### ⭐ The easiest way
-
-**Claude Code:** install the plugin, which includes the server and the skills.
+**Claude Code plugin**
 
 ```
 /plugin marketplace add jigarfumakiya/localship
 /plugin install localship@localship
 ```
 
-**Codex, Cursor, Gemini CLI and other agents:** one command adds the Localship skills,
-step-by-step playbooks your agent follows. The first time, it offers to install the Localship
-command line it uses.
+**Claude Code, Codex, Gemini CLI and other CLIs:** add the server, then the skills.
 
 ```sh
-npx skills add jigarfumakiya/localship
+claude mcp add localship -- npx -y localship mcp   # Claude Code
+codex mcp add localship -- npx -y localship mcp    # Codex
+gemini mcp add localship npx -y localship mcp      # Gemini CLI
+npx skills add jigarfumakiya/localship             # the skills, for any agent
 ```
 
-Then open your app and ask: *"Translate this app into Hindi and Arabic."*
+**Cursor and VS Code**
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=localship&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImxvY2Fsc2hpcCIsIm1jcCJdfQ%3D%3D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522localship%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522localship%2522%252C%2522mcp%2522%255D%257D)
+
+Add the skills too: `npx skills add jigarfumakiya/localship`.
+
+Now ask your agent: *"Translate this app into Hindi and Arabic."* Needs Node.js 22 or newer.
 
 ### 🔌 Other tools
 
-Add Localship as an MCP server.
+Add this MCP server to your tool's config:
 
 ```json
 { "mcpServers": { "localship": { "command": "npx", "args": ["-y", "localship", "mcp"] } } }
 ```
 
-| Tool | Where the config goes |
+| Tool | Config file |
 |---|---|
-| Claude Code (without the plugin) | `claude mcp add localship -- npx -y localship mcp` |
-| Cursor | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` |
-| VS Code | `.vscode/mcp.json`, with `"servers"` instead of `"mcpServers"` and `"type": "stdio"` added |
-| Gemini CLI | `.gemini/settings.json` |
-| Codex | `~/.codex/config.toml`: `[mcp_servers.localship]` with `command = "npx"` and `args = ["-y", "localship", "mcp"]` |
-| Claude Desktop | `claude_desktop_config.json`, with `"-C", "/path/to/your/app"` added before `"mcp"` |
-
-The first start takes a minute while it installs.
+| Cursor | `.cursor/mcp.json` |
+| VS Code | `.vscode/mcp.json` (use `"servers"`) |
+| Claude Desktop | `claude_desktop_config.json` (add `"-C", "/path/to/app"` before `"mcp"`) |
 
 <details>
 <summary><b>MCP tools</b></summary>

package/dist/{chunk-OWT47JBL.js → chunk-QS3UG3KI.js}

@@ -604,8 +604,8 @@ async function matchPattern(fs, root, pattern) {
   }
   return out.sort((a, b) => a.locale.localeCompare(b.locale));
 }
-function inferLocaleStyle(matches, fallback) {
-  for (const m of matches) {
+function inferLocaleStyle(matches2, fallback) {
+  for (const m of matches2) {
     if (/[_@]/.test(m.segment)) return "gettext";
     if (m.segment.includes("-")) return "bcp47";
   }
@@ -1771,14 +1771,14 @@ function escapeString(s) {
   for (const c of s) out += ESCAPES[c] ?? c;
   return out;
 }
-function formatString(keyword, value, width) {
+function formatString(keyword, value, width2) {
   const segments = value.split(/(?<=\n)/).map(escapeString);
   if (segments.length === 0) segments.push("");
   const single = `${keyword} "${segments.join("")}"`;
   const innerNewline = value.indexOf("\n") >= 0 && value.indexOf("\n") < value.length - 1;
-  if (!innerNewline && (width === false || displayWidth(single) <= width)) return [single];
-  const pieces = width === false ? segments : segments.flatMap((seg) => wrapSegment(seg, width - 2));
-  if (!innerNewline && width !== false && pieces.length === 1 && displayWidth(pieces[0] ?? "") > width - 2) {
+  if (!innerNewline && (width2 === false || displayWidth(single) <= width2)) return [single];
+  const pieces = width2 === false ? segments : segments.flatMap((seg) => wrapSegment(seg, width2 - 2));
+  if (!innerNewline && width2 !== false && pieces.length === 1 && displayWidth(pieces[0] ?? "") > width2 - 2) {
     return [single];
   }
   return [`${keyword} ""`, ...pieces.map((s) => `"${s}"`)];
@@ -1826,12 +1826,12 @@ function charWidth(c) {
   if (ZERO_WIDTH.test(c)) return 0;
   return WIDE.test(c) ? 2 : 1;
 }
-function wrapReferences(refs, width) {
-  if (width === false) return [`#: ${refs.join(" ")}`];
+function wrapReferences(refs, width2) {
+  if (width2 === false) return [`#: ${refs.join(" ")}`];
   const lines = [];
   let line = "#:";
   for (const r of refs) {
-    if (line !== "#:" && displayWidth(line) + 1 + displayWidth(r) > width) {
+    if (line !== "#:" && displayWidth(line) + 1 + displayWidth(r) > width2) {
       lines.push(line);
       line = "#:";
     }
@@ -1922,9 +1922,9 @@ var poAdapter = {
       }
       return byKey;
     };
-    const matches = await matchPattern(fs, root, config.path);
-    const style = inferLocaleStyle(matches, "gettext");
-    for (const m of matches) {
+    const matches2 = await matchPattern(fs, root, config.path);
+    const style = inferLocaleStyle(matches2, "gettext");
+    for (const m of matches2) {
       const po = await read2(m.file, m.locale);
       if (po) files.set(m.locale, { file: m.file, po, byKey: indexEntries(po, m.file, m.locale) });
     }
@@ -3694,6 +3694,372 @@ async function runInit(fs, opts, io) {
   }
 }
 
+// src/core/usage.ts
+import path15 from "path";
+var MAX_USAGES = 3;
+var MAX_FILE_BYTES2 = 512 * 1024;
+var ANDROID_CODE2 = /\.(kt|kts|java|xml)$/;
+var SWIFT_CODE = /\.(swift|m|mm)$/;
+var ANDROID_REF = /\bR\.(?:string|plurals|array)\.(\w+)|@(?:string|plurals|array)\/(\w+)/g;
+var STRING_LITERAL = /@?"((?:[^"\\\n]|\\.)*)"/g;
+var APPLE_SPEC = /%%|%(?:\d+\$)?[-+ #0]*\d*(?:\.\d+)?(?:hh|h|ll|l|q|z|t|j)?[@dDuUxXoOfeEgGcCsSaAp]/g;
+var SLOT = "
";
+async function buildUsageIndex(project) {
+  const formats = new Set(project.targets.map((t) => t.target.format));
+  const needsCode = formats.has("android-xml") || formats.has("xcstrings");
+  const files = needsCode ? (await walk(project.fs, project.root)).files : [];
+  const lines = /* @__PURE__ */ new Map();
+  const read2 = async (rel) => {
+    let cached = lines.get(rel);
+    if (!cached) {
+      try {
+        const text = await project.fs.readFile(path15.join(project.root, rel));
+        cached = text.length > MAX_FILE_BYTES2 ? [] : text.split(/\r?\n/);
+      } catch {
+        cached = [];
+      }
+      lines.set(rel, cached);
+    }
+    return cached;
+  };
+  const android = /* @__PURE__ */ new Map();
+  if (formats.has("android-xml")) {
+    for (const rel of files) {
+      if (!ANDROID_CODE2.test(rel) || /(^|\/)res\/values[^/]*\//.test(rel)) continue;
+      const text = await read2(rel);
+      text.forEach((line, i) => {
+        for (const m of line.matchAll(ANDROID_REF)) {
+          const key = m[1] ?? m[2];
+          add(android, key, rel, text, i);
+        }
+      });
+    }
+  }
+  const apple = /* @__PURE__ */ new Map();
+  if (formats.has("xcstrings")) {
+    for (const rel of files) {
+      if (!SWIFT_CODE.test(rel)) continue;
+      const text = await read2(rel);
+      text.forEach((line, i) => {
+        for (const m of line.matchAll(STRING_LITERAL)) {
+          add(apple, normalizeSwiftLiteral(m[1]), rel, text, i);
+        }
+      });
+    }
+  }
+  const po = /* @__PURE__ */ new Map();
+  for (const { target } of project.targets) {
+    if (target.format !== "po") continue;
+    for (const entry of target.source.entries.values()) {
+      const found = [];
+      for (const ref of entry.references ?? []) {
+        if (found.length >= MAX_USAGES) break;
+        const m = /^(.+?):(\d+)$/.exec(ref);
+        const rel = m?.[1] ?? ref;
+        const text = m ? await read2(rel) : [];
+        const i = Number(m?.[2] ?? 0) - 1;
+        found.push(text[i] !== void 0 ? usageAt(rel, text, i) : { at: ref, code: "" });
+      }
+      if (found.length) po.set(`${target.id}\0${entry.key}`, found);
+    }
+  }
+  return {
+    find(target, entry) {
+      switch (target.format) {
+        case "android-xml":
+          return android.get(entry.key) ?? [];
+        case "xcstrings":
+          return apple.get(normalizeCatalogKey(entry.key)) ?? [];
+        case "po":
+          return po.get(`${target.id}\0${entry.key}`) ?? [];
+        default:
+          return [];
+      }
+    }
+  };
+}
+function add(index, key, rel, text, i) {
+  const list = index.get(key) ?? [];
+  if (list.length >= MAX_USAGES) return;
+  if (list.some((u) => u.at.startsWith(`${rel}:`))) return;
+  list.push(usageAt(rel, text, i));
+  index.set(key, list);
+}
+function usageAt(rel, text, i) {
+  const line = text[i] ?? "";
+  let previous;
+  for (let j = i - 1; j >= Math.max(0, i - 3); j--) {
+    const candidate = text[j];
+    if (candidate.trim() === "") continue;
+    if (/^\s*(\/\/|\*|\/\*|#)/.test(candidate)) break;
+    previous = candidate;
+    break;
+  }
+  const picked = previous !== void 0 ? [previous, line] : [line];
+  const indent = Math.min(...picked.map((l) => /^\s*/.exec(l)?.[0].length ?? 0));
+  const code = picked.map((l) => l.slice(indent).trimEnd()).join("\n").slice(0, 240);
+  return { at: `${rel}:${i + 1}`, code };
+}
+function normalizeSwiftLiteral(literal) {
+  let out = "";
+  for (let i = 0; i < literal.length; i++) {
+    const c = literal[i];
+    if (c === "\\" && literal[i + 1] === "(") {
+      let depth = 0;
+      let j = i + 1;
+      for (; j < literal.length; j++) {
+        if (literal[j] === "(") depth++;
+        else if (literal[j] === ")" && --depth === 0) break;
+      }
+      out += SLOT;
+      i = j;
+    } else if (c === "\\" && i + 1 < literal.length) {
+      const n = literal[++i];
+      out += n === "n" ? "\n" : n === "t" ? "	" : n;
+    } else {
+      out += c;
+    }
+  }
+  return out;
+}
+function normalizeCatalogKey(key) {
+  return key.replace(APPLE_SPEC, (m) => m === "%%" ? "%" : SLOT);
+}
+
+// src/core/qa.ts
+function textChecks(s, t, opts = {}) {
+  const out = [];
+  const source = visible(s);
+  const target = visible(t);
+  const language = opts.locale?.split("-")[0] ?? "";
+  if (!opts.countImplied) {
+    const have = numbers(target);
+    for (const n of numbers(source)) {
+      if (DUAL.has(language) && (n === "1" || n === "2")) continue;
+      const i = have.indexOf(n);
+      if (i >= 0) have.splice(i, 1);
+      else
+        out.push({
+          severity: "warning",
+          code: "number-mismatch",
+          message: `The number ${n} from the source is missing`
+        });
+    }
+  }
+  const ending = closing(source);
+  if (ending && !NO_QUESTION_MARK.has(language) && !ending.marks.some((m) => endsWith(target, m))) {
+    out.push({
+      severity: "warning",
+      code: "punctuation-end",
+      message: `The source ends with "${ending.shown}"; the translation doesn't`
+    });
+  }
+  if (isAllCaps(source) && readsLowercase(withoutKeptWords(target, source))) {
+    out.push({
+      severity: "warning",
+      code: "case-mismatch",
+      message: "The source is in capitals (a label or heading); the translation isn't"
+    });
+  }
+  for (const token of [...matches(source, URL), ...matches(source, EMAIL)]) {
+    if (!target.includes(token))
+      out.push({
+        severity: "warning",
+        code: "token-missing",
+        message: `${token} from the source is missing or changed`
+      });
+  }
+  const emoji = matches(target, EMOJI);
+  for (const e of matches(source, EMOJI)) {
+    const i = emoji.indexOf(e);
+    if (i >= 0) emoji.splice(i, 1);
+    else
+      out.push({
+        severity: "warning",
+        code: "token-missing",
+        message: `The emoji ${e} from the source is missing`
+      });
+  }
+  return out;
+}
+function visible(a) {
+  let text = a.text;
+  for (const p of a.placeholders) text = text.split(p.raw).join(" ");
+  return text;
+}
+function numbers(text) {
+  const out = [];
+  for (const m of text.matchAll(new RegExp("\\p{Nd}+(?:[.,\xA0\u202F'\u2019]\\p{Nd}+)*", "gu"))) {
+    const digits = [...m[0]].filter((c) => new RegExp("\\p{Nd}", "u").test(c)).map(digitValue);
+    out.push(digits.join(""));
+  }
+  return out;
+}
+var ZEROS = [
+  48,
+  1632,
+  1776,
+  1984,
+  2406,
+  2534,
+  2662,
+  2790,
+  2918,
+  3046,
+  3174,
+  3302,
+  3430,
+  3558,
+  3664,
+  3792,
+  3872,
+  4160,
+  4240,
+  6112,
+  6160,
+  6470,
+  6608,
+  43216,
+  43264,
+  65296
+];
+function digitValue(c) {
+  const cp = c.codePointAt(0) ?? 0;
+  const zero = ZEROS.find((z4) => cp >= z4 && cp <= z4 + 9);
+  return zero === void 0 ? c : String(cp - zero);
+}
+var ENDINGS = [
+  { shown: "?", marks: ["?", "\uFF1F", "\u061F", ";"] },
+  { shown: "!", marks: ["!", "\uFF01"] },
+  { shown: ":", marks: [":", "\uFF1A", "\uFE55"] },
+  { shown: "\u2026", marks: ["\u2026", "...", "\u22EF", "\u2025"] }
+];
+var DUAL = /* @__PURE__ */ new Set(["ar", "he", "iw"]);
+var NO_QUESTION_MARK = /* @__PURE__ */ new Set(["th", "lo", "km", "my"]);
+function closing(text) {
+  const end = trimEnd(text);
+  if (end.endsWith("...")) return ENDINGS[3];
+  return ENDINGS.find((e) => end.endsWith(e.shown));
+}
+function endsWith(text, mark) {
+  return trimEnd(text).endsWith(mark);
+}
+function trimEnd(text) {
+  return text.replace(/[\s"'”’»)\]}」』]+$/u, "");
+}
+function withoutKeptWords(text, source) {
+  const kept = new Set(source.toLowerCase().match(new RegExp("\\p{L}+", "gu")) ?? []);
+  return text.replace(new RegExp("\\p{L}+", "gu"), (w) => kept.has(w.toLowerCase()) ? " " : w);
+}
+function isAllCaps(text) {
+  const cased = [...text].filter(hasCase);
+  return cased.length >= 2 && cased.every((c) => c === c.toUpperCase());
+}
+function readsLowercase(text) {
+  const letters = [...text].filter((c) => new RegExp("\\p{L}", "u").test(c));
+  const cased = letters.filter(hasCase);
+  if (cased.length < 2 || cased.length * 2 < letters.length) return false;
+  const lower = cased.filter((c) => c !== c.toUpperCase()).length;
+  return lower > cased.length - lower;
+}
+function hasCase(c) {
+  return c.toLowerCase() !== c.toUpperCase();
+}
+var URL = /https?:\/\/[^\s<>"')\]]+[^\s<>"')\].,;:!?]/gu;
+var EMAIL = /[\p{L}\p{N}._%+-]+@[\p{L}\p{N}-]+(?:\.[\p{L}\p{N}-]+)+/gu;
+var EMOJI = new RegExp("\\p{Extended_Pictographic}", "gu");
+function matches(text, pattern) {
+  return [...text.matchAll(pattern)].map((m) => m[0]);
+}
+function inconsistencies(project, locales) {
+  const out = [];
+  for (const locale2 of locales) {
+    const bySource = /* @__PURE__ */ new Map();
+    for (const { target } of project.targets) {
+      const catalog = target.locales.get(locale2);
+      if (!catalog) continue;
+      for (const src of target.source.entries.values()) {
+        if (!src.translatable || src.message.kind !== "text") continue;
+        const tgt = catalog.entries.get(src.key);
+        if (tgt?.message.kind !== "text") continue;
+        const source = normalize(target.analyze(src.message.value, src).text);
+        const group = `${src.context ?? ""}${source}`;
+        const translation2 = normalize(target.analyze(tgt.message.value, src).text);
+        if (!source || !translation2) continue;
+        const ways = bySource.get(group) ?? /* @__PURE__ */ new Map();
+        const list = ways.get(translation2) ?? [];
+        list.push({ target: target.id, entry: tgt });
+        ways.set(translation2, list);
+        bySource.set(group, ways);
+      }
+    }
+    for (const [group, ways] of bySource) {
+      if (ways.size < 2) continue;
+      const source = group.slice(group.indexOf("") + 1);
+      const sorted = [...ways].sort((a, b) => b[1].length - a[1].length);
+      const odd = sorted.at(-1)?.[1][0];
+      const listed = sorted.slice(0, 3).map(
+        ([text, at]) => `"${short(text)}" (${at.map((x) => displayKey(x.entry.key)).join(", ")})`
+      ).join(", ");
+      out.push({
+        severity: "warning",
+        code: "inconsistent",
+        message: `"${short(source)}" is translated ${ways.size} ways: ${listed}. Fine if the context differs`,
+        locale: locale2,
+        ...odd ? { target: odd.target, key: odd.entry.key, file: odd.entry.file, line: odd.entry.line } : {}
+      });
+    }
+  }
+  return out;
+}
+var normalize = (text) => text.trim().replace(/\s+/g, " ");
+var short = (text) => text.length > 40 ? `${text.slice(0, 39)}\u2026` : text;
+var ROLES = [
+  ["accessibility label", /contentDescription|accessibility(?:Label|Hint)/],
+  ["placeholder", /\bplaceholder\b|android:hint|\bhint\s*=|\b(?:Secure)?TextField\(/],
+  // Design systems wrap these (`AppButton`, `SmChip`), so any name ending in the kind counts.
+  ["tab", /\b\w*Tab\s*\(|Navigation(?:Bar|Rail)Item|BottomNavigationItem|\.tabItem\b/],
+  ["chip", /\b\w*Chip\s*\(/],
+  [
+    "button",
+    /\b\w*Button\s*[({]|<(?:\w+\.)*\w*Button\b|(?:confirm|dismiss)Button|set(?:Positive|Negative|Neutral)Button/
+  ],
+  ["menu item", /DropdownMenuItem|<item\b[^>]*android:title|\bMenu\s*\{/],
+  ["toast", /Toast\.makeText|showSnackbar|Snackbar(?:\.make)?\(/],
+  ["notification", /setContent(?:Title|Text)|NotificationCompat|UNMutableNotificationContent/],
+  ["app name", /android:label=/],
+  ["title", /TopAppBar|\btitle\s*=|\.navigationTitle\(|setTitle\(|\.alert\(/]
+];
+function roleOf(usages) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const u of usages) {
+    const lines = u.code.split("\n").reverse();
+    const role = lines.map((line) => ROLES.find(([, pattern]) => pattern.test(line))?.[0]).find((r) => r !== void 0);
+    if (role) counts.set(role, (counts.get(role) ?? 0) + 1);
+  }
+  return [...counts].sort((a, b) => b[1] - a[1])[0]?.[0];
+}
+var TIGHT = /* @__PURE__ */ new Set(["button", "tab", "chip", "menu item", "app name"]);
+function lengthCheck(role, s, t) {
+  if (!role || !TIGHT.has(role)) return void 0;
+  const source = width(visible(s).trim());
+  const target = width(visible(t).trim());
+  if (source === 0 || target <= source * 2 || target - source < 6) return void 0;
+  return {
+    severity: "warning",
+    code: "too-long",
+    message: `Used as a ${role}: about ${target} characters wide against ${source} in the source, so it may not fit`
+  };
+}
+function width(text) {
+  let w = 0;
+  for (const c of text) {
+    if (new RegExp("\\p{M}|\u200B|\u200C|\u200D", "u").test(c)) continue;
+    w += new RegExp("[\u1100-\u115F\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6]|\\p{Extended_Pictographic}", "u").test(c) ? 2 : 1;
+  }
+  return w;
+}
+
 // src/core/validate.ts
 function validateProject(project, opts = {}) {
   const locales = opts.locales ?? projectLocales(project);
@@ -3785,12 +4151,14 @@ function validateProject(project, opts = {}) {
           ...checkTranslation(loaded, spec, src, tgt, {
             locale: locale2,
             sourceLocale: project.config.sourceLocale,
-            glossary: project.context.glossary
+            glossary: project.context.glossary,
+            role: opts.usages ? roleOf(opts.usages.find(loaded, src)) : void 0
           }).map((i) => ({ ...where, ...i }))
         );
       }
     }
   }
+  issues.push(...inconsistencies(project, locales));
   return issues;
 }
 function checkSource(target, src) {
@@ -3845,7 +4213,8 @@ function checkTranslation(target, spec, src, tgt, opts) {
     allowed,
     strictNewlines: target.strictNewlines,
     glossary: opts.glossary,
-    locale: locale2
+    locale: locale2,
+    role: opts.role
   }).map((f) => form ? { ...f, form } : f);
   if (s.kind === "text" && t.kind === "text") return compare(s.value, t.value);
   if (s.kind === "array" && t.kind === "array") {
@@ -4001,6 +4370,11 @@ function compareValues(s, t, opts = {}) {
   if (opts.glossary?.length && opts.locale && t.text.trim() !== "") {
     out.push(...checkGlossary(opts.glossary, opts.locale, s.text, t.text));
   }
+  if (t.text.trim() !== "") {
+    out.push(...textChecks(s, t, { countImplied: opts.countImplied, locale: opts.locale }));
+    const long = lengthCheck(opts.role, s, t);
+    if (long) out.push(long);
+  }
   const edge = (x) => [/^\s*/.exec(x)?.[0] ?? "", /\s*$/.exec(x)?.[0] ?? ""];
   const [sl, st] = edge(s.text);
   const [tl, tt] = edge(t.text);
@@ -4031,140 +4405,6 @@ function describeNewlines(text) {
 
 // src/core/workflow.ts
 import { z as z3 } from "zod";
-
-// src/core/usage.ts
-import path15 from "path";
-var MAX_USAGES = 3;
-var MAX_FILE_BYTES2 = 512 * 1024;
-var ANDROID_CODE2 = /\.(kt|kts|java|xml)$/;
-var SWIFT_CODE = /\.(swift|m|mm)$/;
-var ANDROID_REF = /\bR\.(?:string|plurals|array)\.(\w+)|@(?:string|plurals|array)\/(\w+)/g;
-var STRING_LITERAL = /@?"((?:[^"\\\n]|\\.)*)"/g;
-var APPLE_SPEC = /%%|%(?:\d+\$)?[-+ #0]*\d*(?:\.\d+)?(?:hh|h|ll|l|q|z|t|j)?[@dDuUxXoOfeEgGcCsSaAp]/g;
-var SLOT = "
";
-async function buildUsageIndex(project) {
-  const formats = new Set(project.targets.map((t) => t.target.format));
-  const needsCode = formats.has("android-xml") || formats.has("xcstrings");
-  const files = needsCode ? (await walk(project.fs, project.root)).files : [];
-  const lines = /* @__PURE__ */ new Map();
-  const read2 = async (rel) => {
-    let cached = lines.get(rel);
-    if (!cached) {
-      try {
-        const text = await project.fs.readFile(path15.join(project.root, rel));
-        cached = text.length > MAX_FILE_BYTES2 ? [] : text.split(/\r?\n/);
-      } catch {
-        cached = [];
-      }
-      lines.set(rel, cached);
-    }
-    return cached;
-  };
-  const android = /* @__PURE__ */ new Map();
-  if (formats.has("android-xml")) {
-    for (const rel of files) {
-      if (!ANDROID_CODE2.test(rel) || /(^|\/)res\/values[^/]*\//.test(rel)) continue;
-      const text = await read2(rel);
-      text.forEach((line, i) => {
-        for (const m of line.matchAll(ANDROID_REF)) {
-          const key = m[1] ?? m[2];
-          add(android, key, rel, text, i);
-        }
-      });
-    }
-  }
-  const apple = /* @__PURE__ */ new Map();
-  if (formats.has("xcstrings")) {
-    for (const rel of files) {
-      if (!SWIFT_CODE.test(rel)) continue;
-      const text = await read2(rel);
-      text.forEach((line, i) => {
-        for (const m of line.matchAll(STRING_LITERAL)) {
-          add(apple, normalizeSwiftLiteral(m[1]), rel, text, i);
-        }
-      });
-    }
-  }
-  const po = /* @__PURE__ */ new Map();
-  for (const { target } of project.targets) {
-    if (target.format !== "po") continue;
-    for (const entry of target.source.entries.values()) {
-      const found = [];
-      for (const ref of entry.references ?? []) {
-        if (found.length >= MAX_USAGES) break;
-        const m = /^(.+?):(\d+)$/.exec(ref);
-        const rel = m?.[1] ?? ref;
-        const text = m ? await read2(rel) : [];
-        const i = Number(m?.[2] ?? 0) - 1;
-        found.push(text[i] !== void 0 ? usageAt(rel, text, i) : { at: ref, code: "" });
-      }
-      if (found.length) po.set(`${target.id}\0${entry.key}`, found);
-    }
-  }
-  return {
-    find(target, entry) {
-      switch (target.format) {
-        case "android-xml":
-          return android.get(entry.key) ?? [];
-        case "xcstrings":
-          return apple.get(normalizeCatalogKey(entry.key)) ?? [];
-        case "po":
-          return po.get(`${target.id}\0${entry.key}`) ?? [];
-        default:
-          return [];
-      }
-    }
-  };
-}
-function add(index, key, rel, text, i) {
-  const list = index.get(key) ?? [];
-  if (list.length >= MAX_USAGES) return;
-  if (list.some((u) => u.at.startsWith(`${rel}:`))) return;
-  list.push(usageAt(rel, text, i));
-  index.set(key, list);
-}
-function usageAt(rel, text, i) {
-  const line = text[i] ?? "";
-  let previous;
-  for (let j = i - 1; j >= Math.max(0, i - 3); j--) {
-    const candidate = text[j];
-    if (candidate.trim() === "") continue;
-    if (/^\s*(\/\/|\*|\/\*|#)/.test(candidate)) break;
-    previous = candidate;
-    break;
-  }
-  const picked = previous !== void 0 ? [previous, line] : [line];
-  const indent = Math.min(...picked.map((l) => /^\s*/.exec(l)?.[0].length ?? 0));
-  const code = picked.map((l) => l.slice(indent).trimEnd()).join("\n").slice(0, 240);
-  return { at: `${rel}:${i + 1}`, code };
-}
-function normalizeSwiftLiteral(literal) {
-  let out = "";
-  for (let i = 0; i < literal.length; i++) {
-    const c = literal[i];
-    if (c === "\\" && literal[i + 1] === "(") {
-      let depth = 0;
-      let j = i + 1;
-      for (; j < literal.length; j++) {
-        if (literal[j] === "(") depth++;
-        else if (literal[j] === ")" && --depth === 0) break;
-      }
-      out += SLOT;
-      i = j;
-    } else if (c === "\\" && i + 1 < literal.length) {
-      const n = literal[++i];
-      out += n === "n" ? "\n" : n === "t" ? "	" : n;
-    } else {
-      out += c;
-    }
-  }
-  return out;
-}
-function normalizeCatalogKey(key) {
-  return key.replace(APPLE_SPEC, (m) => m === "%%" ? "%" : SLOT);
-}
-
-// src/core/workflow.ts
 function itemId(item) {
   return `${item.target}\0${item.locale}\0${item.key}`;
 }
@@ -4190,13 +4430,13 @@ function plainText(target, entry) {
   const value = entry.message.kind === "plural" ? entry.message.forms.other ?? values.at(-1)?.[1] : values.map(([, v]) => v).join("\n");
   return target.analyze(value ?? "", entry).text;
 }
-var normalize = (s) => s.trim().replace(/\s+/g, " ");
+var normalize2 = (s) => s.trim().replace(/\s+/g, " ");
 function buildMemory(project, locales) {
   const memory = /* @__PURE__ */ new Map();
   for (const { target } of project.targets) {
     for (const src of target.source.entries.values()) {
       if (!src.translatable) continue;
-      const text = normalize(plainText(target, src));
+      const text = normalize2(plainText(target, src));
       if (!text) continue;
       for (const locale2 of locales) {
         const tgt = target.locales.get(locale2)?.entries.get(src.key);
@@ -4211,6 +4451,25 @@ function buildMemory(project, locales) {
   }
   return memory;
 }
+function differentWording(target, src, message, locale2, memory, thisBatch) {
+  if (message.kind !== "text" || src.context) return void 0;
+  const source = normalize2(plainText(target, src));
+  if (!source) return void 0;
+  const value = normalize2(message.value);
+  const id2 = `${locale2}\0${source}`;
+  const earlier = thisBatch.get(id2);
+  thisBatch.set(id2, earlier ?? { key: displayKey(src.key), value });
+  const existing = (memory.get(source) ?? []).filter(
+    (m) => m.locale === locale2 && (m.target !== target.id || m.key !== src.key) && typeof m.value === "string"
+  ).map((m) => ({ key: displayKey(m.key), value: normalize2(m.value) }))[0];
+  const other = existing ?? earlier;
+  if (!other || other.value === value) return void 0;
+  return {
+    severity: "warning",
+    code: "inconsistent",
+    message: `"${source}" is already translated as "${other.value}" (${other.key}). Use the same wording unless the context differs`
+  };
+}
 async function nextBatch(project, opts = {}) {
   const usages = opts.usages === void 0 ? await buildUsageIndex(project) : opts.usages;
   const locales = opts.locales ?? projectLocales(project);
@@ -4241,6 +4500,8 @@ async function nextBatch(project, opts = {}) {
         matched++;
         if (matched <= offset || items.length >= limit) continue;
         const text = plainText(target, src);
+        const found = usages ? usages.find(target, src) : [];
+        const role = roleOf(found);
         const placeholders = [
           ...new Set(
             messageValues(src.message).flatMap(
@@ -4249,7 +4510,7 @@ async function nextBatch(project, opts = {}) {
           )
         ];
         const hits = glossaryHits(glossary, text);
-        const matches = (memory.get(normalize(text)) ?? []).filter(
+        const matches2 = (memory.get(normalize2(text)) ?? []).filter(
           (m) => m.locale === locale2 && !(m.target === target.id && m.key === src.key)
         );
         const item = {
@@ -4261,7 +4522,9 @@ async function nextBatch(project, opts = {}) {
           source: toValue(src.message),
           ...src.comment ? { comment: src.comment } : {},
           ...src.context ? { context: src.context } : {},
-          ...usageFields(usages ? usages.find(target, src) : [], src.references),
+          ...usageFields(found, src.references),
+          ...role ? { role } : {},
+          ...tgt && lockEntry?.note ? { note: lockEntry.note } : {},
           ...tgt ? { current: toValue(tgt.message) } : {},
           ...state === "stale" && lockEntry?.sourceText !== void 0 ? { previousSource: lockEntry.sourceText } : {},
           ...handEdited ? { editedByHand: true } : {},
@@ -4284,8 +4547,8 @@ async function nextBatch(project, opts = {}) {
               };
             })
           } : {},
-          ...matches.length ? {
-            memory: matches.slice(0, 3).map((m) => ({
+          ...matches2.length ? {
+            memory: matches2.slice(0, 3).map((m) => ({
               value: m.value,
               from: `${m.target}:${displayKey(m.key)}`
             }))
@@ -4332,7 +4595,8 @@ var SubmissionSchema = z3.object({
   target: z3.string().optional(),
   locale: z3.string(),
   key: z3.string(),
-  value: MessageValueSchema
+  value: MessageValueSchema,
+  note: z3.string().optional()
 });
 var SubmitInputSchema = z3.union([
   z3.array(SubmissionSchema),
@@ -4361,6 +4625,10 @@ async function submit(project, submissions, opts = {}) {
   const configured = projectLocales(project);
   const pending = /* @__PURE__ */ new Map();
   const seen = /* @__PURE__ */ new Set();
+  const memory = buildMemory(project, configured);
+  const thisBatch = /* @__PURE__ */ new Map();
+  const usages = opts.usages === void 0 ? await buildUsageIndex(project) : opts.usages;
+  const notes = /* @__PURE__ */ new Map();
   for (const sub of submissions) {
     const reject = (message2, code = "rejected", target2) => result.rejected.push({
       ...target2 ? { target: target2 } : {},
@@ -4434,7 +4702,8 @@ async function submit(project, submissions, opts = {}) {
       ...checkTranslation(target, target.pluralSpec(locale2), src, tgt, {
         locale: locale2,
         sourceLocale: project.config.sourceLocale,
-        glossary: project.context.glossary
+        glossary: project.context.glossary,
+        role: usages ? roleOf(usages.find(target, src)) : void 0
       }).filter((f) => f.code !== "plural-missing-category" && f.code !== "plural-extra-category"),
       ...checkPluralForms(target, locale2, message)
     ];
@@ -4443,6 +4712,8 @@ async function submit(project, submissions, opts = {}) {
       result.rejected.push({ target: target.id, locale: locale2, key: displayKey(src.key), errors });
       continue;
     }
+    const differs = differentWording(target, src, message, locale2, memory, thisBatch);
+    if (differs) findings.push(differs);
     result.accepted.push({
       target: target.id,
       locale: locale2,
@@ -4454,6 +4725,7 @@ async function submit(project, submissions, opts = {}) {
     entries.set(src.key, tgt);
     byLocale.set(locale2, entries);
     pending.set(target, byLocale);
+    notes.set(id2, sub.note?.trim() || null);
   }
   if (opts.dryRun || pending.size === 0) return result;
   const files = /* @__PURE__ */ new Set();
@@ -4466,7 +4738,12 @@ async function submit(project, submissions, opts = {}) {
   result.files = [...files].sort();
   const keys = [...pending].flatMap(
     ([target, byLocale]) => [...byLocale].flatMap(
-      ([locale2, entries]) => [...entries.keys()].map((key) => ({ target: target.id, locale: locale2, key }))
+      ([locale2, entries]) => [...entries.keys()].map((key) => ({
+        target: target.id,
+        locale: locale2,
+        key,
+        note: notes.get(`${target.id}\0${locale2}\0${key}`) ?? null
+      }))
     )
   );
   await record(project, keys, () => ({
@@ -4565,11 +4842,13 @@ async function record(project, keys, entry) {
     const tgt = target?.locales.get(k.locale)?.entries.get(k.key);
     if (!src || !tgt) continue;
     const previous = getLockEntry(lock, k.target, k.locale, k.key);
+    const note = k.note === void 0 ? previous?.note : k.note ?? void 0;
     setLockEntry(lock, k.target, k.locale, k.key, {
       source: hashMessage(src.message),
       sourceText: toValue(src.message),
       target: hashMessage(tgt.message),
-      ...entry(previous)
+      ...entry(previous),
+      ...note ? { note } : {}
     });
   }
   pruneLock(fresh, lock);
@@ -5400,6 +5679,7 @@ export {
   printApprove,
   printPlan,
   runInit,
+  buildUsageIndex,
   validateProject,
   nextBatch,
   SubmissionSchema,
@@ -5413,4 +5693,4 @@ export {
   TRANSLATION_RULES,
   translateProject
 };
-//# sourceMappingURL=chunk-OWT47JBL.js.map
+//# sourceMappingURL=chunk-QS3UG3KI.js.map

package/dist/cli.js

@@ -4,6 +4,7 @@ import {
   UserError,
   addLocales,
   approve,
+  buildUsageIndex,
   computeStatus,
   describeDetect,
   describeNone,
@@ -29,13 +30,13 @@ import {
   submit,
   translateProject,
   validateProject
-} from "./chunk-OWT47JBL.js";
+} from "./chunk-QS3UG3KI.js";
 
 // src/cli/main.ts
 import path from "path";
 import { createInterface } from "readline/promises";
 import { Command, InvalidArgumentError } from "commander";
-var VERSION = true ? "0.1.0" : "dev";
+var VERSION = true ? "0.2.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);
@@ -75,7 +76,11 @@ program.command("status").description("Translation progress per locale").option(
 });
 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 });
+  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));
@@ -291,7 +296,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-GZNS57EQ.js");
+  const { runServer } = await import("./server-T6GQ6CV5.js");
   const explicit = program.getOptionValueSource("cwd") !== "default";
   const cwd = explicit ? globals().cwd : process.env.CLAUDE_PROJECT_DIR ?? globals().cwd;
   await runServer({ cwd, version: VERSION });

package/dist/{server-GZNS57EQ.js → server-T6GQ6CV5.js}

@@ -7,6 +7,7 @@ import {
   UserError,
   addLocales,
   approve,
+  buildUsageIndex,
   computeStatus,
   detect,
   hardcodedNotes,
@@ -24,7 +25,7 @@ import {
   translateProject,
   validateProject,
   writeContext
-} from "./chunk-OWT47JBL.js";
+} from "./chunk-QS3UG3KI.js";
 
 // src/mcp/server.ts
 import { existsSync, readFileSync } from "fs";
@@ -112,7 +113,8 @@ function createServer(opts) {
       strict: z.boolean().optional().describe("Untranslated strings and missing locales are errors")
     },
     async ({ cwd, locales, strict }) => {
-      const issues = validateProject(await project(cwd), { locales, strict });
+      const p = await project(cwd);
+      const issues = validateProject(p, { locales, strict, usages: await buildUsageIndex(p) });
       return { ok: !issues.some((i) => i.severity === "error"), issues };
     },
     { readOnlyHint: true }
@@ -212,7 +214,7 @@ ${TRANSLATION_RULES}`,
   );
   tool(
     "localship_submit",
-    "Check translations and write the ones without errors as drafts. Rejected ones come back with the errors to fix; resubmit just those. value is a string, an object of plural forms, or an array, matching the item's kind.",
+    "Check translations and write the ones without errors as drafts. Rejected ones come back with the errors to fix; resubmit just those. value is a string, an object of plural forms, or an array, matching the item's kind. Add a short note only when the source is ambiguous, saying how you read it.",
     {
       cwd: cwdArg,
       translations: z.array(SubmissionSchema),
@@ -311,4 +313,4 @@ export {
   createServer,
   runServer
 };
-//# sourceMappingURL=server-GZNS57EQ.js.map
+//# sourceMappingURL=server-T6GQ6CV5.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localship",
-  "version": "0.1.0",
+  "version": "0.2.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",

package/skills/localship-review/SKILL.md

@@ -23,7 +23,8 @@ installed, ask to install it once with `npm install -g localship`.
    localship next-batch --locale hi --states draft
    ```
    Each item shows `source` and the translation as `current`, with the comment, plural forms
-   and glossary. Read `.localship/brief.md` and the locale's voice first.
+   and glossary. A `note` says how the translator read an ambiguous source: check that reading
+   first, and mention it to the user if you're not sure. `role` says where it appears. Read `.localship/brief.md` and the locale's voice first.
    To review translations made before Localship, use `--states untracked`; for hand edits,
    `--states edited`. Fixing those replaces a person's work, so ask before resubmitting, and
    pass `--force` only then.

package/skills/localship-translate/SKILL.md

@@ -64,7 +64,11 @@ come out generic.
      one).
    - Arrays: same number of items, same order.
    - Reuse `memory` unless the context differs. Follow the glossary.
-   - Keep it about as long as the source; buttons and tabs have little room.
+   - Keep it about as long as the source. Items with a `role` of button, tab, chip or menu item
+     have little room: prefer the shortest natural wording.
+   - When the source could mean two things ("Open" as a button or a status, "Balance" as money
+     or equilibrium) and the context doesn't settle it, add a short `note` saying how you read
+     it. Reviewers see it. Skip notes when the meaning is clear.
    - Android values: write plain text; apostrophes, quotes and `&` are escaped for you.
 
 3. Submit, using a file for anything non-trivial:
@@ -77,7 +81,8 @@ come out generic.
      {"target": "android", "locale": "hi", "key": "days_left", "value": {"one": "%d दिन बाकी", "other": "%d दिन बाकी"}}
    ]}
    ```
-   Copy `target`, `locale` and `key` from the batch items. Delete the file afterwards.
+   Copy `target`, `locale` and `key` from the batch items. Add `"note"` to an entry only for an
+   ambiguous source. Delete the file afterwards.
 
 4. Read the result. Rejected entries list their errors: fix exactly those and resubmit only
    them. Accepted entries may have warnings (glossary, untranslated, whitespace): fix the