localship 0.1.0 → 0.3.0

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

@@ -341,15 +341,58 @@ async function addLocales(fs, file, requested) {
 }
 
 // src/core/fs.ts
+import { randomUUID } from "crypto";
 import { promises as fsp } from "fs";
+import os from "os";
 import path2 from "path";
+function busy(file) {
+  return new UserError(
+    `Another Localship write is in progress (${file}). Retry after it finishes. If a process crashed, verify no writer is running before removing this lock.`
+  );
+}
+async function renameWithRetry(from, to) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await fsp.rename(from, to);
+      return;
+    } catch (e) {
+      const code = e.code;
+      if (attempt >= 20 || !(code === "EPERM" || code === "EACCES" || code === "EBUSY")) throw e;
+      await new Promise((resolve) => setTimeout(resolve, 10 + attempt * 10));
+    }
+  }
+}
 var nodeFs = {
   readFile: (file) => fsp.readFile(file, "utf8"),
   async writeFile(file, content) {
     await fsp.mkdir(path2.dirname(file), { recursive: true });
-    const tmp = `${file}.${process.pid}.tmp`;
-    await fsp.writeFile(tmp, content, "utf8");
-    await fsp.rename(tmp, file);
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      await fsp.writeFile(tmp, content, { encoding: "utf8", flag: "wx" });
+      await renameWithRetry(tmp, file);
+    } finally {
+      await fsp.rm(tmp, { force: true });
+    }
+  },
+  async withLock(file, run) {
+    await fsp.mkdir(path2.dirname(file), { recursive: true });
+    const handle = await fsp.open(file, "wx").catch((e) => {
+      if (e.code === "EEXIST") throw busy(file);
+      throw e;
+    });
+    try {
+      await handle.writeFile(
+        JSON.stringify({
+          pid: process.pid,
+          host: os.hostname(),
+          started: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+      return await run();
+    } finally {
+      await handle.close();
+      await fsp.unlink(file);
+    }
   },
   async exists(file) {
     try {
@@ -426,6 +469,29 @@ function voiceFor(context, locale2) {
   const text = parts.filter(Boolean).join("\n\n");
   return text || void 0;
 }
+var VOICE_CONVENTIONS = {
+  hi: "Address the user as \u0906\u092A (polite). Everyday Hindi over Sanskritized words; common English tech words (app, sync) may stay in English.",
+  ar: "Modern Standard Arabic, addressing the user neutrally. Short sentences.",
+  de: "Address the user as du, as most consumer apps do.",
+  fr: "Address the user as vous.",
+  es: "Address the user as t\xFA. Neutral Spanish that works in Spain and Latin America.",
+  it: "Address the user as tu.",
+  "pt-BR": "Address the user as voc\xEA (Brazilian Portuguese conventions).",
+  "pt-PT": "European Portuguese spelling and vocabulary (utilizador, ecr\xE3), not Brazilian.",
+  nl: "Address the user as je.",
+  ru: "Address the user as \u0432\u044B (lowercase).",
+  ja: "Polite \u3067\u3059/\u307E\u3059 form. Short, natural UI phrasing.",
+  ko: "Polite \uD574\uC694\uCCB4. Short, natural UI phrasing.",
+  zh: "Neutral, concise UI language; no honorifics needed.",
+  tr: "Address the user as siz.",
+  pl: "Address the user informally (ty), as most consumer apps do.",
+  id: "Address the user as Anda.",
+  vi: "Address the user as b\u1EA1n.",
+  th: "Polite, neutral tone; use \u0E04\u0E23\u0E31\u0E1A/\u0E04\u0E48\u0E30 only where a sentence needs it."
+};
+function conventionalVoice(locale2) {
+  return VOICE_CONVENTIONS[locale2] ?? VOICE_CONVENTIONS[locale2.split("-")[0]] ?? "Polite, neutral tone, as a well-made app in this language would use.";
+}
 var WORD = "[\\p{L}\\p{M}\\p{N}]";
 var escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 function glossaryHits(glossary, text) {
@@ -604,8 +670,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";
   }
@@ -615,18 +681,40 @@ function inferLocaleStyle(matches, fallback) {
 // src/core/plurals.ts
 var SAMPLE_INTEGERS = [...Array.from({ length: 1001 }, (_, i) => i), 1e4, 1e6];
 var SAMPLE_DECIMALS = [0.5, 1.5, 2.5];
+var specs = /* @__PURE__ */ new Map();
+var copySpec = (spec) => ({
+  ...spec,
+  forms: spec.forms.map((form) => ({ ...form }))
+});
 function pluralCategories(locale2) {
   const found = new Intl.PluralRules(locale2).resolvedOptions().pluralCategories;
   return PLURAL_CATEGORIES.filter((c) => found.includes(c));
 }
 function cldrPluralSpec(locale2) {
+  const key = Intl.getCanonicalLocales(locale2)[0] ?? locale2;
+  const cached = specs.get(key);
+  if (cached) return copySpec(cached);
   const rules = new Intl.PluralRules(locale2);
-  return {
+  const integers = /* @__PURE__ */ new Map();
+  const fractions = /* @__PURE__ */ new Map();
+  for (const [samples, grouped] of [
+    [SAMPLE_INTEGERS, integers],
+    [SAMPLE_DECIMALS, fractions]
+  ]) {
+    for (const n of samples) {
+      const category = rules.select(n);
+      const values = grouped.get(category) ?? [];
+      values.push(n);
+      grouped.set(category, values);
+    }
+  }
+  const categories = rules.resolvedOptions().pluralCategories;
+  const spec = {
     scheme: "cldr",
     source: "CLDR",
-    forms: pluralCategories(locale2).map((id2) => {
-      const ints = SAMPLE_INTEGERS.filter((n) => rules.select(n) === id2);
-      const decimals = SAMPLE_DECIMALS.filter((n) => rules.select(n) === id2);
+    forms: PLURAL_CATEGORIES.filter((id2) => categories.includes(id2)).map((id2) => {
+      const ints = integers.get(id2) ?? [];
+      const decimals = fractions.get(id2) ?? [];
       return {
         id: id2,
         examples: describeSamples(ints, decimals),
@@ -635,6 +723,10 @@ function cldrPluralSpec(locale2) {
       };
     })
   };
+  const oldest = specs.keys().next().value;
+  if (specs.size >= 256 && oldest !== void 0) specs.delete(oldest);
+  specs.set(key, spec);
+  return copySpec(spec);
 }
 function describeSamples(ints, decimals = []) {
   const shown = ints.slice(0, 5).map(String);
@@ -1020,6 +1112,7 @@ var androidAdapter = {
     const issues = [];
     const rootAttrs = /* @__PURE__ */ new Map();
     const localeFiles = /* @__PURE__ */ new Map();
+    let hasQualifiedStrings = false;
     const target = {
       id: id2,
       format: "android-xml",
@@ -1045,8 +1138,7 @@ var androidAdapter = {
     const dirs = (await fs.listDir(resDir)).filter((d) => d.isDirectory && d.name.startsWith("values")).map((d) => d.name).sort();
     for (const dir of dirs) {
       const locale2 = folderToLocale(dir);
-      if (locale2 === void 0) continue;
-      const catalog = locale2 === null ? source : { locale: locale2, entries: /* @__PURE__ */ new Map() };
+      const catalog = locale2 === null ? source : { locale: locale2 ?? sourceLocale, entries: /* @__PURE__ */ new Map() };
       const xmlFiles = (await fs.listDir(path5.join(resDir, dir))).filter((f) => !f.isDirectory && f.name.endsWith(".xml")).map((f) => f.name).sort();
       for (const name of xmlFiles) {
         const abs = path5.join(resDir, dir, name);
@@ -1069,6 +1161,30 @@ var androidAdapter = {
         }
         const resources = doc.root;
         if (resources?.name !== "resources") continue;
+        if (locale2 === void 0) {
+          const qualified = { locale: sourceLocale, entries: /* @__PURE__ */ new Map() };
+          readEntries(
+            doc,
+            resources,
+            rel,
+            qualified,
+            (issue) => issues.push({ ...issue, target: id2 })
+          );
+          if (qualified.entries.size > 0) hasQualifiedStrings = true;
+          const entries = [...qualified.entries.values()].filter((e) => e.translatable);
+          if (entries.length > 0) {
+            issues.push({
+              severity: "warning",
+              blocksCompleteness: true,
+              code: "resource-configuration-unsupported",
+              message: `${entries.length} string resource${entries.length === 1 ? "" : "s"} in ${dir} use configuration qualifiers that Localship cannot validate or translate. Preserved unchanged; check this configuration with Android lint and on a device.`,
+              target: id2,
+              file: rel,
+              line: entries[0]?.line
+            });
+          }
+          continue;
+        }
         const before = catalog.entries.size;
         const spans = /* @__PURE__ */ new Map();
         readEntries(
@@ -1087,7 +1203,17 @@ var androidAdapter = {
           );
         }
       }
-      if (locale2 !== null && catalog.entries.size > 0) locales.set(locale2, catalog);
+      if (locale2 !== null && locale2 !== void 0 && catalog.entries.size > 0)
+        locales.set(locale2, catalog);
+    }
+    if (source.entries.size === 0 && (locales.size > 0 || hasQualifiedStrings)) {
+      issues.push({
+        severity: "error",
+        code: "default-resources-missing",
+        message: "String resources exist in qualified folders, but this target has no default strings in values. Restore the defaults or configure the target containing them; verify merged resources with Android lint.",
+        target: id2,
+        file: relativePath(root, path5.join(resDir, "values"))
+      });
     }
     async function writeLocale(catalog) {
       const folder = path5.join(resDir, localeToFolder(catalog.locale));
@@ -1771,14 +1897,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 +1952,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 +2048,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) });
     }
@@ -2387,6 +2513,11 @@ function deletePath(root, path17) {
 // src/formats/xcstrings/adapter.ts
 var order = (a, b) => a.localeCompare(b, "en");
 var UNREVIEWED = /* @__PURE__ */ new Set(["needs_review", "new", "stale"]);
+function hasUnsupportedVariation(loc) {
+  return !!loc.substitutions || !!loc.variations && (Object.keys(loc.variations).some((axis) => axis !== "plural") || Object.values(loc.variations.plural ?? {}).some(
+    (form) => form.variations || form.substitutions
+  ));
+}
 var xcstringsAdapter = {
   format: "xcstrings",
   async open(config, { fs, root, sourceLocale, id: id2 }) {
@@ -2474,23 +2605,35 @@ var xcstringsAdapter = {
       });
     }
     const strings = child(doc, "strings");
-    let unsupported = 0;
     for (const e of strings?.kind === "object" ? strings.entries : []) {
       const key = e.key;
       const info = toJs(e.value) ?? {};
       const locs = info.localizations ?? {};
-      const variant = Object.values(locs).some((l) => l.substitutions || l.variations?.device);
-      if (variant) unsupported++;
+      const variant = Object.values(locs).some(hasUnsupportedVariation);
       const line = lineOf(e.offset);
+      const intended = key !== "" && info.shouldTranslate !== false && info.extractionState !== "stale";
+      if (intended && variant) {
+        issues.push({
+          severity: "warning",
+          blocksCompleteness: true,
+          code: "variation-unsupported",
+          message: "Device, nested or other unsupported variations or substitutions are present; this entire key is preserved but excluded from translation and validation. Review it in Xcode; Localship cannot certify completeness for this catalog.",
+          target: id2,
+          key,
+          file: rel,
+          line
+        });
+      }
+      const own = read(locs[sourceLanguage]);
       const base = {
         key,
         // "" is Xcode's placeholder for empty Text(""); stale strings are gone from the code.
-        translatable: key !== "" && info.shouldTranslate !== false && info.extractionState !== "stale" && !variant,
+        // Keys with no words (" ", "·", "%@%@") come from text built in pieces: nothing to translate.
+        translatable: intended && !variant && hasWords(own?.message ?? { kind: "text", value: key }),
         file: rel,
         line
       };
       if (info.comment) base.comment = info.comment;
-      const own = read(locs[sourceLanguage]);
       source.entries.set(key, { ...base, message: own?.message ?? { kind: "text", value: key } });
       if (!base.translatable) continue;
       for (const [locale2, loc] of Object.entries(locs)) {
@@ -2507,15 +2650,6 @@ var xcstringsAdapter = {
         catalog.entries.set(key, entry);
       }
     }
-    if (unsupported > 0) {
-      issues.push({
-        severity: "info",
-        code: "variation-unsupported",
-        message: `${unsupported} string${unsupported === 1 ? " uses" : "s use"} device variations or substitutions, which aren't supported yet; skipped`,
-        target: id2,
-        file: rel
-      });
-    }
     async function writeLocale(catalog) {
       if (!doc) throw new Error(`${rel} could not be read, so it can't be written`);
       for (const entry of catalog.entries.values()) {
@@ -2592,6 +2726,11 @@ function sortDeep(v) {
     Object.keys(v).sort(order).map((k) => [k, sortDeep(v[k])])
   );
 }
+var FORMAT_SPECIFIER = /%(?:\d+\$)?[-+ #0]*\d*(?:\.\d+)?(?:hh|h|ll|l|q|z|t|j)?[@dDuUxXoOfFeEgGcCsSpaA%]/g;
+function hasWords(message) {
+  const values = message.kind === "text" ? [message.value] : message.kind === "plural" ? Object.values(message.forms) : message.items;
+  return values.some((v) => new RegExp("\\p{L}", "u").test(v.replace(FORMAT_SPECIFIER, "")));
+}
 
 // src/core/lock.ts
 function emptyLock() {
@@ -2658,6 +2797,20 @@ async function openProject(fs, opts) {
     fs
   };
 }
+function projectGlossary(project) {
+  const known = new Set(project.context.glossary.map((t) => t.term.toLowerCase()));
+  const extra = [];
+  for (const { target } of project.targets) {
+    if (target.format !== "android-xml") continue;
+    const entry = target.source.entries.get("app_name");
+    const value = entry?.message.kind === "text" ? messageValues(entry.message)[0]?.[1] : void 0;
+    const name = entry && value ? target.analyze(value, entry).text.trim() : "";
+    if (!name || known.has(name.toLowerCase())) continue;
+    known.add(name.toLowerCase());
+    extra.push({ term: name, translate: false, caseSensitive: false });
+  }
+  return extra.length ? [...project.context.glossary, ...extra] : project.context.glossary;
+}
 function openTarget(fs, root, config, sourceLocale, id2) {
   const adapter = ADAPTERS[config.format];
   return adapter.open(config, { fs, root, sourceLocale, id: id2 });
@@ -2665,6 +2818,15 @@ function openTarget(fs, root, config, sourceLocale, id2) {
 function reopenProject(project) {
   return openProject(project.fs, { cwd: project.root, config: project.configFile });
 }
+async function withProjectWrite(project, dryRun, run) {
+  if (dryRun) return run(project);
+  return project.fs.withLock(path8.join(project.root, ".localship", "write.lock"), async () => {
+    const fresh = await reopenProject(project);
+    const result = await run(fresh);
+    project.lock = fresh.lock;
+    return result;
+  });
+}
 function findTarget(project, id2) {
   return project.targets.find((t) => t.target.id === id2)?.target;
 }
@@ -3167,7 +3329,7 @@ async function detectXcstrings(fs, root, files) {
       locales: [...t.locales.keys()].sort(),
       ...declared ? { sourceLocale: declared } : {},
       questions: strings === 0 ? [
-        "The catalog is empty. Build the app in Xcode once so it collects your strings, then run detect again."
+        "The catalog is empty. Build the targets that use it, then fill it: Xcode's catalog editor does this with the project open; from the command line, run `xcrun xcstringstool sync <catalog> --stringsdata <each target's .stringsdata in DerivedData>`, since a command-line build alone leaves the catalog unchanged. Then run detect again."
       ] : []
     });
   }
@@ -3209,12 +3371,12 @@ function hints(files, candidates, unsupported, hardcoded) {
   }
   const has = (format) => candidates.some((c) => c.target.format === format);
   const appleLegacy = unsupported.some((u) => u.format.startsWith("Apple"));
-  const xcode = files.some(
-    (f) => f.endsWith(".xcodeproj/project.pbxproj") || f === "project.yml" || f.endsWith("/project.yml")
-  );
+  const generator = files.some((f) => /(^|\/)project\.yml$/.test(f)) ? "XcodeGen (project.yml)" : files.some((f) => /(^|\/)Project\.swift$/.test(f)) ? "Tuist (Project.swift)" : void 0;
+  const xcode = !!generator || files.some((f) => f.endsWith(".xcodeproj/project.pbxproj"));
   if (xcode && !has("xcstrings") && !appleLegacy) {
+    const add2 = generator ? `The project is generated by ${generator}: put a Localizable.xcstrings in each target's sources and set SWIFT_EMIT_LOC_STRINGS there, then regenerate; changes made in Xcode are lost when the project is regenerated` : "Add one in Xcode (File \u203A New \u203A File \u203A String Catalog, named Localizable) to each target that shows text";
     out.push(
-      `This looks like an Xcode project without a String Catalog. Add one in Xcode (File \u203A New \u203A File \u203A String Catalog, named Localizable) and build: Xcode fills it with your SwiftUI Text strings. Text built from variables needs moving to String(localized:) first (the localship-extract skill helps)${iosCode ? `; UIKit code also has ${hardcodedSummary(iosCode)}` : ""}. Then run detect again.`
+      `This looks like an Xcode project without a String Catalog. ${add2}. Build, and fill the catalog from the build: Xcode's catalog editor does this; from the command line use \`xcrun xcstringstool sync\`. Text built from variables needs moving to String(localized:) first (the localship-extract skill helps)${iosCode ? `; UIKit code also has ${hardcodedSummary(iosCode)}` : ""}. Then run detect again.`
     );
   }
   const gradle = files.some((f) => /(^|\/)build\.gradle(\.kts)?$/.test(f));
@@ -3276,6 +3438,7 @@ function entryState(source, target, lock) {
   if (!lock) return target.needsReview ? "draft" : "untracked";
   if (lock.source !== hashMessage(source.message)) return "stale";
   if (lock.target !== hashMessage(target.message)) return "edited";
+  if (target.needsReview && lock.state === "approved") return "draft";
   return lock.state;
 }
 function editedByHand(target, lock) {
@@ -3305,6 +3468,15 @@ function computeStatus(project, locales = projectLocales(project)) {
 function statusNotes(project, locales = projectLocales(project)) {
   const notes = [];
   for (const { target: loaded } of project.targets) {
+    for (const issue of loaded.issues) {
+      if (!issue.blocksCompleteness || issue.severity === "error") continue;
+      notes.push({
+        target: loaded.id,
+        severity: "warning",
+        code: issue.code,
+        message: `${issue.file ? `${issue.file}: ` : ""}${issue.message}`
+      });
+    }
     const errors = loaded.issues.filter((i) => i.severity === "error");
     const byCode = /* @__PURE__ */ new Map();
     for (const e of errors) byCode.set(e.code, (byCode.get(e.code) ?? 0) + 1);
@@ -3327,7 +3499,7 @@ function statusNotes(project, locales = projectLocales(project)) {
         locale: locale2,
         severity: "warning",
         code: "orphan",
-        message: `${orphans.length} translation${orphans.length === 1 ? "" : "s"} of deleted strings; \`localship prune\` removes ${orphans.length === 1 ? "it" : "them"}`
+        message: `${orphans.length} translation${orphans.length === 1 ? "" : "s"} without a matching source; restore missing defaults or, after confirming the keys are unused, remove them with \`localship prune\``
       });
     }
   }
@@ -3520,31 +3692,30 @@ function printPlan(p) {
   if (p.locales.length) {
     const per = Math.max(0, ...Object.values(p.work));
     const total = Object.values(p.work).reduce((a, b) => a + b, 0);
-    const about = p.ready ? "" : "about ";
-    const count = p.locales.length > 1 ? `${about}${per} strings, ${total} translations` : `${about}${per} strings`;
+    const count = p.locales.length > 1 ? `${per} strings, ${total} translations` : `${per} strings`;
     console.log(
       `Languages: ${p.locales.map((l) => `${l.name} (${l.code}${l.isNew ? ", new" : ""})`).join(", ")} \xB7 ${count}`
     );
   }
   for (const w of p.warnings) console.log(`${yellow("\u25B2")} ${w}`);
-  for (const b of p.blockers) console.log(`${yellow("\u25B2")} ${b.message}`);
-  console.log();
-  console.log(bold("Plan"));
-  for (const [i, s] of p.steps.entries()) console.log(`  ${i + 1}. ${s}`);
-  if (p.locales.length || p.defaults.keepAsWritten.length) {
+  for (const b of p.blockers) console.log(`${yellow("\u25B2")} ${b.message} ${dim(b.fix)}`);
+  for (const n of p.notes) console.log(`${dim("\xB7")} ${n}`);
+  if (p.locales.length) {
     console.log();
-    console.log(bold("Defaults") + dim(" (change any of them before starting)"));
-    for (const [l, v] of Object.entries(p.defaults.voice)) console.log(`  ${l}: ${v}`);
-    if (p.defaults.keepAsWritten.length) {
-      console.log(`  Kept as written: ${p.defaults.keepAsWritten.join(", ")}`);
+    console.log(bold("Translators go by"));
+    for (const [l, v] of Object.entries(p.voice)) {
+      console.log(`  ${l}: ${v.text}${v.fromProject ? "" : dim(" (usual convention)")}`);
     }
+    if (p.keepAsWritten.length) console.log(`  Kept as written: ${p.keepAsWritten.join(", ")}`);
+    if (!p.brief)
+      console.log(dim("  No brief yet (.localship/brief.md); the README gives context."));
   }
   console.log();
   const codes = p.locales.map((l) => l.code).join(",");
   console.log(
-    !p.confirm ? yellow("Sort out the item above first.") : p.ready ? green(
-      `Ready. Tell your agent "${p.confirm}", or run \`localship start ${codes} --model \u2026\` to translate here.`
-    ) : green(`Tell your agent "${p.confirm}" to begin with step 1 (that step needs an agent).`)
+    p.ready ? green(
+      `Ready. Ask your agent to translate, or run \`localship start ${codes} --model \u2026\` to translate here.`
+    ) : yellow("Sort out the item above first.")
   );
 }
 
@@ -3694,139 +3865,536 @@ async function runInit(fs, opts, io) {
   }
 }
 
-// src/core/validate.ts
-function validateProject(project, opts = {}) {
-  const locales = opts.locales ?? projectLocales(project);
-  const issues = [];
-  for (const { target: loaded } of project.targets) {
-    issues.push(...loaded.issues);
-    const at = (e, locale2) => ({
-      target: loaded.id,
-      locale: locale2,
-      key: e.key,
-      file: e.file,
-      line: e.line
-    });
-    for (const src of loaded.source.entries.values()) {
-      if (!src.translatable) continue;
-      issues.push(
-        ...checkSource(loaded, src).map((i) => ({ ...at(src, loaded.source.locale), ...i }))
-      );
-    }
-    for (const locale2 of locales) {
-      const catalog = loaded.locales.get(locale2);
-      if (!catalog) {
-        issues.push({
-          severity: opts.strict ? "error" : "info",
-          code: "locale-missing",
-          message: `No ${locale2} translations yet`,
-          target: loaded.id,
-          locale: locale2
-        });
-        continue;
-      }
-      const spec = loaded.pluralSpec(locale2);
-      const hasPlurals = [...catalog.entries.values()].some((e) => e.message.kind === "plural");
-      if (!spec && hasPlurals) {
-        issues.push({
-          severity: "warning",
-          code: "plural-forms-unknown",
-          message: `Plural rules for ${locale2} are unknown, so plural forms were not checked`,
-          target: loaded.id,
-          locale: locale2
-        });
-      }
-      let missing = 0;
-      for (const src of loaded.source.entries.values()) {
-        if (src.translatable && !catalog.entries.has(src.key)) {
-          missing++;
-          if (opts.strict) {
-            issues.push({
-              ...at(src, locale2),
-              severity: "error",
-              code: "missing",
-              message: "Not translated"
-            });
-          }
-        }
-      }
-      if (missing > 0 && !opts.strict) {
-        issues.push({
-          severity: "info",
-          code: "missing",
-          message: `${missing} string${missing === 1 ? "" : "s"} not translated yet`,
-          target: loaded.id,
-          locale: locale2
-        });
+// 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 = [];
       }
-      for (const tgt of catalog.entries.values()) {
-        const src = loaded.source.entries.get(tgt.key);
-        const where = at(tgt, locale2);
-        if (!src) {
-          issues.push({
-            ...where,
-            severity: "warning",
-            code: "orphan",
-            message: "Not in the source strings any more"
-          });
-          continue;
-        }
-        if (!src.translatable && hashMessage(src.message) !== hashMessage(tgt.message)) {
-          issues.push({
-            ...where,
-            severity: "warning",
-            code: "not-translatable",
-            message: 'Source is marked translatable="false"; remove this translation'
-          });
-          continue;
+      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);
         }
-        if (!src.translatable) continue;
-        issues.push(
-          ...checkTranslation(loaded, spec, src, tgt, {
-            locale: locale2,
-            sourceLocale: project.config.sourceLocale,
-            glossary: project.context.glossary
-          }).map((i) => ({ ...where, ...i }))
-        );
-      }
+      });
     }
   }
-  return issues;
-}
-function checkSource(target, src) {
-  const out = [];
-  const each = (value, form) => {
-    const a = target.analyze(value, src);
-    for (const l of a.lints) out.push({ ...l, ...form ? { form } : {} });
-    const loose = a.placeholders.filter((p) => !p.positional);
-    if (loose.length > 1 && !target.translationsMayReorder) {
-      const printf2 = loose.every((p) => p.raw.startsWith("%") && p.type);
-      out.push({
-        severity: "warning",
-        code: "placeholder-not-positional",
-        message: printf2 ? `Use numbered placeholders (${loose.map((p, i) => `%${i + 1}$${p.type}`).join(", ")}) so translators can reorder them` : `${loose.map((p) => p.raw).join(", ")} can't be reordered; name or number them so translators can`,
-        ...form ? { form } : {}
+  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 m = src.message;
-  if (m.kind === "text") each(m.value);
-  else if (m.kind === "array") {
-    for (const [i, v] of m.items.entries()) each(v, String(i));
-  } else {
-    if (m.forms.other === void 0 && Object.keys(m.forms).some((k) => !/^\d+$/.test(k))) {
-      out.push({
-        severity: "error",
-        code: "plural-missing-category",
-        message: 'Plural has no "other" form'
-      });
+  }
+  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);
     }
-    for (const [c, v] of Object.entries(m.forms)) each(v, c);
   }
-  return out;
-}
-function checkTranslation(target, spec, src, tgt, opts) {
-  const { locale: locale2, sourceLocale } = opts;
+  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;
+        if (getLockEntry(project.lock, target.id, locale2, src.key)?.note) 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}. If the context differs, add a note to the translation saying how`,
+        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);
+  const strict = opts.strict || opts.requireApproved;
+  const issues = [];
+  if (opts.requireApproved && locales.length === 0) {
+    issues.push({
+      severity: "error",
+      code: "locales-empty",
+      message: "No target locales to check; configure locales or select them with --locale"
+    });
+  }
+  for (const { target: loaded } of project.targets) {
+    issues.push(
+      ...loaded.issues.map(
+        (issue) => strict && issue.blocksCompleteness ? { ...issue, severity: "error" } : issue
+      )
+    );
+    const at = (e, locale2) => ({
+      target: loaded.id,
+      locale: locale2,
+      key: e.key,
+      file: e.file,
+      line: e.line
+    });
+    for (const src of loaded.source.entries.values()) {
+      if (!src.translatable) continue;
+      issues.push(
+        ...checkSource(loaded, src).map((i) => ({ ...at(src, loaded.source.locale), ...i }))
+      );
+    }
+    for (const locale2 of locales) {
+      const catalog = loaded.locales.get(locale2);
+      if (!catalog) {
+        issues.push({
+          severity: strict ? "error" : "info",
+          code: "locale-missing",
+          message: `No ${locale2} translations yet`,
+          target: loaded.id,
+          locale: locale2
+        });
+        continue;
+      }
+      const spec = loaded.pluralSpec(locale2);
+      const hasPlurals = [...catalog.entries.values()].some((e) => e.message.kind === "plural");
+      if (!spec && hasPlurals) {
+        issues.push({
+          severity: "warning",
+          code: "plural-forms-unknown",
+          message: `Plural rules for ${locale2} are unknown, so plural forms were not checked`,
+          target: loaded.id,
+          locale: locale2
+        });
+      }
+      let missing = 0;
+      for (const src of loaded.source.entries.values()) {
+        if (src.translatable && !catalog.entries.has(src.key)) {
+          missing++;
+          if (strict) {
+            issues.push({
+              ...at(src, locale2),
+              severity: "error",
+              code: "missing",
+              message: "Not translated"
+            });
+          }
+        }
+      }
+      if (missing > 0 && !strict) {
+        issues.push({
+          severity: "info",
+          code: "missing",
+          message: `${missing} string${missing === 1 ? "" : "s"} not translated yet`,
+          target: loaded.id,
+          locale: locale2
+        });
+      }
+      for (const tgt of catalog.entries.values()) {
+        const src = loaded.source.entries.get(tgt.key);
+        const where = at(tgt, locale2);
+        if (!src) {
+          issues.push({
+            ...where,
+            severity: strict && loaded.format === "android-xml" ? "error" : "warning",
+            code: "orphan",
+            message: loaded.format === "android-xml" ? "No matching default resource in this target's values folder; restore the default, or remove this translation only if the key is no longer used. Check merged resources with Android lint." : "Not in the source strings any more"
+          });
+          continue;
+        }
+        if (!src.translatable && hashMessage(src.message) !== hashMessage(tgt.message)) {
+          issues.push({
+            ...where,
+            severity: "warning",
+            code: "not-translatable",
+            message: 'Source is marked translatable="false"; remove this translation'
+          });
+          continue;
+        }
+        if (!src.translatable) continue;
+        if (opts.requireApproved) {
+          const state = entryState(
+            src,
+            tgt,
+            getLockEntry(project.lock, loaded.id, locale2, src.key)
+          );
+          if (state !== "approved") {
+            const reason = state === "stale" ? "Source changed since this translation was recorded" : state === "edited" ? "Translation was edited since it was recorded" : `Translation is ${state}`;
+            issues.push({
+              ...where,
+              severity: "error",
+              code: "not-approved",
+              message: `${reason}; review it against the current source and approve it`
+            });
+          }
+        }
+        issues.push(
+          ...checkTranslation(loaded, spec, src, tgt, {
+            locale: locale2,
+            sourceLocale: project.config.sourceLocale,
+            glossary: projectGlossary(project),
+            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) {
+  const out = [];
+  const each = (value, form) => {
+    const a = target.analyze(value, src);
+    for (const l of a.lints) out.push({ ...l, ...form ? { form } : {} });
+    const loose = a.placeholders.filter((p) => !p.positional);
+    if (loose.length > 1 && !target.translationsMayReorder) {
+      const printf2 = loose.every((p) => p.raw.startsWith("%") && p.type);
+      out.push({
+        severity: "warning",
+        code: "placeholder-not-positional",
+        message: printf2 ? `Use numbered placeholders (${loose.map((p, i) => `%${i + 1}$${p.type}`).join(", ")}) so translators can reorder them` : `${loose.map((p) => p.raw).join(", ")} can't be reordered; name or number them so translators can`,
+        ...form ? { form } : {}
+      });
+    }
+  };
+  const m = src.message;
+  if (m.kind === "text") each(m.value);
+  else if (m.kind === "array") {
+    for (const [i, v] of m.items.entries()) each(v, String(i));
+  } else {
+    if (m.forms.other === void 0 && Object.keys(m.forms).some((k) => !/^\d+$/.test(k))) {
+      out.push({
+        severity: "error",
+        code: "plural-missing-category",
+        message: 'Plural has no "other" form'
+      });
+    }
+    for (const [c, v] of Object.entries(m.forms)) each(v, c);
+  }
+  return out;
+}
+function checkTranslation(target, spec, src, tgt, opts) {
+  const { locale: locale2, sourceLocale } = opts;
   const t = tgt.message;
   const s = src.message.kind === "text" && t.kind === "plural" ? { kind: "plural", forms: { other: src.message.value } } : src.message;
   if (s.kind !== t.kind) {
@@ -3845,7 +4413,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 +4570,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 +4605,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 +4630,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 +4651,25 @@ function buildMemory(project, locales) {
   }
   return memory;
 }
+function differentWording(target, src, message, locale2, memory, thisBatch, note) {
+  if (message.kind !== "text" || src.context || note) 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, or add a note saying how 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);
@@ -4219,7 +4678,7 @@ async function nextBatch(project, opts = {}) {
   const offset = opts.offset ?? 0;
   const wanted = opts.keys ? new Set(opts.keys) : void 0;
   const memory = buildMemory(project, locales);
-  const glossary = project.context.glossary;
+  const glossary = projectGlossary(project);
   const items = [];
   let matched = 0;
   for (const locale2 of locales) {
@@ -4241,6 +4700,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 +4710,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 +4722,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 +4747,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)}`
             }))
@@ -4304,7 +4767,13 @@ async function nextBatch(project, opts = {}) {
     locales: Object.fromEntries(
       usedLocales.map((l) => {
         const voice = voiceFor(project.context, l);
-        return [l, { language: languageName(l), ...voice ? { voice } : {} }];
+        return [
+          l,
+          {
+            language: languageName(l),
+            ...voice ? { voice } : { defaultVoice: conventionalVoice(l) }
+          }
+        ];
       })
     ),
     formats: Object.fromEntries(
@@ -4332,7 +4801,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),
@@ -4357,10 +4827,21 @@ ${details.join("\n")}`
 }
 var REPLACEABLE = ["missing", "stale", "draft"];
 async function submit(project, submissions, opts = {}) {
+  return withProjectWrite(
+    project,
+    opts.dryRun,
+    (fresh) => submitUnlocked(fresh, submissions, opts)
+  );
+}
+async function submitUnlocked(project, submissions, opts) {
   const result = { accepted: [], rejected: [], files: [], dryRun: !!opts.dryRun };
   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 } : {},
@@ -4392,6 +4873,17 @@ async function submit(project, submissions, opts = {}) {
       continue;
     }
     const { target, src } = found;
+    const expected = opts.expectedSources?.get(
+      itemId({ target: target.id, locale: locale2, key: displayKey(src.key) })
+    );
+    if (expected !== void 0 && JSON.stringify(expected) !== JSON.stringify(toValue(src.message))) {
+      reject(
+        "The source changed while the model was translating; translate the current source",
+        "source-changed",
+        target.id
+      );
+      continue;
+    }
     const id2 = `${target.id}\0${locale2}\0${src.key}`;
     if (seen.has(id2)) {
       reject("Submitted twice in one batch", "duplicate", target.id);
@@ -4434,7 +4926,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: projectGlossary(project),
+        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 +4936,16 @@ 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,
+      sub.note?.trim()
+    );
+    if (differs) findings.push(differs);
     result.accepted.push({
       target: target.id,
       locale: locale2,
@@ -4454,6 +4957,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 +4970,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 +5074,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);
@@ -4591,6 +5102,9 @@ function pruneLock(project, lock) {
   }
 }
 async function approve(project, opts = {}) {
+  return withProjectWrite(project, opts.dryRun, (fresh) => approveUnlocked(fresh, opts));
+}
+async function approveUnlocked(project, opts) {
   const locales = opts.locales ?? projectLocales(project);
   const states = opts.states ?? ["draft", "reviewed"];
   const to = opts.to ?? "approved";
@@ -4639,6 +5153,9 @@ async function approve(project, opts = {}) {
 }
 var DISPOSABLE = ["draft", "stale"];
 async function removeTranslations(project, opts) {
+  return withProjectWrite(project, opts.dryRun, (fresh) => removeUnlocked(fresh, opts));
+}
+async function removeUnlocked(project, opts) {
   if (!opts.keys?.length && !opts.states?.length) {
     throw new UserError("Say which translations to remove: keys, states (e.g. draft), or both");
   }
@@ -4684,6 +5201,9 @@ async function removeTranslations(project, opts) {
   return result;
 }
 async function prune(project, opts = {}) {
+  return withProjectWrite(project, opts.dryRun, (fresh) => pruneUnlocked(fresh, opts));
+}
+async function pruneUnlocked(project, opts) {
   const result = { removed: [], lockEntries: 0, files: [], dryRun: !!opts.dryRun };
   const plan2 = /* @__PURE__ */ new Map();
   for (const { target } of project.targets) {
@@ -4725,29 +5245,6 @@ async function prune(project, opts = {}) {
 
 // src/core/plan.ts
 import path16 from "path";
-import { stringify as toYaml } from "yaml";
-var VOICE_DEFAULTS = {
-  hi: "Address the user as \u0906\u092A (polite). Everyday Hindi over Sanskritized words; common English tech words (app, sync) may stay in English.",
-  ar: "Modern Standard Arabic, addressing the user neutrally. Short sentences.",
-  de: "Address the user as du, as most consumer apps do.",
-  fr: "Address the user as vous.",
-  es: "Address the user as t\xFA. Neutral Spanish that works in Spain and Latin America.",
-  it: "Address the user as tu.",
-  pt: "Address the user as voc\xEA (Brazilian Portuguese conventions).",
-  nl: "Address the user as je.",
-  ru: "Address the user as \u0432\u044B (lowercase).",
-  ja: "Polite \u3067\u3059/\u307E\u3059 form. Short, natural UI phrasing.",
-  ko: "Polite \uD574\uC694\uCCB4. Short, natural UI phrasing.",
-  zh: "Neutral, concise UI language; no honorifics needed.",
-  tr: "Address the user as siz.",
-  pl: "Address the user informally (ty), as most consumer apps do.",
-  id: "Address the user as Anda.",
-  vi: "Address the user as b\u1EA1n.",
-  th: "Polite, neutral tone; use \u0E04\u0E23\u0E31\u0E1A/\u0E04\u0E48\u0E30 only where a sentence needs it."
-};
-function defaultVoice(locale2) {
-  return VOICE_DEFAULTS[locale2] ?? VOICE_DEFAULTS[locale2.split("-")[0]] ?? "Polite, neutral tone, as a well-made app in this language would use.";
-}
 var COMMON_LANGUAGES = "af am ar az be bg bn bs ca cs cy da de el en es et eu fa fi fil fr ga gl gu he hi hr hu hy id is it ja ka kk km kn ko ky lo lt lv mk ml mn mr ms my nb ne nl or pa pl ps pt ro ru si sk sl sq sr sv sw ta te th tl tr uk ur uz vi zh zu pt-BR pt-PT zh-Hans zh-Hant es-419 fr-CA en-GB".split(" ");
 var NAMES = new Intl.DisplayNames(["en"], { type: "language" });
 function resolveLocale(input) {
@@ -4768,7 +5265,7 @@ function resolveLocale(input) {
 }
 async function appNames(fs, root, result) {
   const names = /* @__PURE__ */ new Set();
-  for (const c of result?.candidates ?? []) {
+  for (const c of result.candidates) {
     if (c.target.format !== "android-xml") continue;
     try {
       const xml = await fs.readFile(path16.join(root, c.target.path, "values", "strings.xml"));
@@ -4777,12 +5274,6 @@ async function appNames(fs, root, result) {
     } catch {
     }
   }
-  try {
-    const readme = await fs.readFile(path16.join(root, "README.md"));
-    const heading = /^#\s+(.+)$/m.exec(readme)?.[1]?.replace(/[^\p{L}\p{N} .-]/gu, "").trim();
-    if (heading && heading.split(/\s+/).length <= 3) names.add(heading);
-  } catch {
-  }
   return [...names];
 }
 async function plan(fs, cwd, opts = {}) {
@@ -4795,12 +5286,14 @@ async function plan(fs, cwd, opts = {}) {
   }
   return project ? planConfigured(project, requested) : planNew(fs, cwd, requested);
 }
+var EXTRACT = "They won't be translated until they're moved into string resources (the localship-extract skill): part of making the app work in a language, otherwise only when the user asks.";
 async function planNew(fs, cwd, requested) {
   const result = await detect(fs, path16.resolve(cwd));
   const picked = defaultSelection(result).map((n) => result.candidates[n - 1]);
   const chosen = picked.filter((c) => c !== void 0);
   const locales = requested.length ? requested : result.locales;
   const blockers = [];
+  const notes = [];
   if (chosen.length === 0) {
     const unsupported = result.unsupported.map((u) => u.format).join(", ");
     blockers.push(
@@ -4811,40 +5304,29 @@ async function planNew(fs, cwd, requested) {
       } : {
         kind: "no-translation-files",
         message: `No translation files yet. ${result.hints[0] ?? ""}`.trim(),
-        fix: "Move the UI text out of the code into string resources (the localship-extract skill), on a new branch, then set up translation."
+        fix: "Move the UI text out of the code into string resources (the localship-extract skill): part of making the app work in a language, otherwise only when the user asks."
       }
     );
   }
   for (const c of chosen) {
     if (c.codeLiterals !== void 0 && mostlyHardcoded(c.codeLiterals, c.strings)) {
-      blockers.push({
-        kind: "mostly-hardcoded",
-        message: `About ${c.codeLiterals} pieces of UI text are still in the code, against ${c.strings} in ${c.target.path}. Translating now would leave most of the app in English.`,
-        fix: `First move that text into ${c.target.path}/values/strings.xml on a new branch (the localship-extract skill), building as it goes, then translate.`
-      });
+      notes.push(
+        `About ${c.codeLiterals} pieces of UI text are still in the code, against ${c.strings} strings in ${c.target.path}. ${EXTRACT}`
+      );
     }
     if (c.target.format === "xcstrings" && c.strings === 0) {
       blockers.push({
         kind: "empty-catalog",
         message: `${c.target.path} is empty.`,
-        fix: "Build the app in Xcode once so it collects your strings into the catalog."
+        fix: "Build the targets that use it, then fill it: Xcode's catalog editor does this with the project open; from the command line, run `xcrun xcstringstool sync <catalog> --stringsdata <each target's .stringsdata in DerivedData>`, since a command-line build alone leaves the catalog unchanged."
       });
     }
   }
-  if (locales.length === 0) {
-    blockers.push({
-      kind: "no-locales",
-      message: "No languages chosen yet.",
-      fix: "Tell me which languages to translate into (for example: Hindi and Arabic)."
-    });
-  }
-  const strings = chosen.reduce(
-    (n, c) => n + c.strings + (c.codeLiterals !== void 0 && mostlyHardcoded(c.codeLiterals, c.strings) ? c.codeLiterals : 0),
-    0
-  );
-  const keep = await appNames(fs, path16.resolve(cwd), result);
+  if (locales.length === 0) blockers.push(noLocales);
+  const strings = chosen.reduce((n, c) => n + c.strings, 0);
   return build({
     warnings: result.otherSystems.map((o) => o.message),
+    notes,
     configured: false,
     sourceLocale: result.sourceLocale.value,
     locales: locales.map((code) => ({ code, name: languageName(code), isNew: true })),
@@ -4855,10 +5337,16 @@ async function planNew(fs, cwd, requested) {
     })),
     work: Object.fromEntries(locales.map((l) => [l, strings])),
     blockers,
-    keep,
-    hasBrief: false
+    keep: await appNames(fs, path16.resolve(cwd), result),
+    brief: false,
+    voice: () => void 0
   });
 }
+var noLocales = {
+  kind: "no-locales",
+  message: "No languages chosen yet.",
+  fix: "Ask the user which languages to translate into."
+};
 async function planConfigured(project, requested) {
   const configured = projectLocales(project);
   const locales = [.../* @__PURE__ */ new Set([...configured, ...requested])].filter(
@@ -4876,22 +5364,12 @@ async function planConfigured(project, requested) {
       );
     }
   }
-  const blockers = (await hardcodedNotes(project)).map((n) => ({
-    kind: "mostly-hardcoded",
-    message: n.message,
-    fix: "First move that text into strings.xml on a new branch (the localship-extract skill), then translate."
-  }));
-  if (focus.length === 0) {
-    blockers.push({
-      kind: "no-locales",
-      message: "No languages chosen yet.",
-      fix: "Tell me which languages to translate into."
-    });
-  }
+  const notes = (await hardcodedNotes(project)).map((n) => `${n.message} ${EXTRACT}`);
   const { files } = await walk(project.fs, project.root);
   const others = await findOtherSystems(project.fs, project.root, files);
   return build({
     warnings: others.map((o) => o.message),
+    notes,
     configured: true,
     sourceLocale: project.config.sourceLocale,
     locales: focus.map((code) => ({
@@ -4905,43 +5383,18 @@ async function planConfigured(project, requested) {
       strings: [...t.target.source.entries.values()].filter((e) => e.translatable).length
     })),
     work,
-    blockers,
-    keep: project.context.glossary.filter((t) => !t.translate).map((t) => t.term),
-    hasBrief: !!project.context.brief,
-    voices: project.context.voice
+    blockers: focus.length ? [] : [noLocales],
+    keep: projectGlossary(project).filter((t) => !t.translate).map((t) => t.term),
+    brief: !!project.context.brief,
+    voice: (l) => voiceFor(project.context, l)
   });
 }
 function build(p) {
   const voice = Object.fromEntries(
-    p.locales.map((l) => [l.code, p.voices?.[l.code] ?? defaultVoice(l.code)])
-  );
-  const fixFirst = p.blockers.filter((b) => b.kind !== "no-locales");
-  const names = p.locales.map((l) => l.name).join(" and ");
-  const total = Math.max(0, ...Object.values(p.work));
-  const steps = [];
-  for (const b of fixFirst) steps.push(b.fix);
-  if (!p.configured) {
-    steps.push(
-      `Set up Localship for ${p.targets.map((t) => t.path).join(", ") || "the app"} with ${names || "your languages"} (localship_start).`
-    );
-  } else if (p.locales.some((l) => l.isNew)) {
-    steps.push(
-      `Add ${p.locales.filter((l) => l.isNew).map((l) => l.name).join(" and ")} (localship_start).`
-    );
-  }
-  if (!p.hasBrief) {
-    steps.push(
-      "Draft a short brief from your README and strings, so translations match the app's tone."
-    );
-  }
-  const about = fixFirst.some((b) => b.kind === "mostly-hardcoded") ? "about " : "";
-  steps.push(
-    `Translate ${total ? `${about}${total}` : "the"} strings${names ? ` into ${names}` : ""}, checking each one (localship_next_batch \u2192 localship_submit until nothing remains).`,
-    "Run all checks (localship_validate) and report what was done.",
-    "Leave everything as drafts for you to review; nothing is approved without you."
-  );
-  const blocked = p.blockers.some(
-    (b) => b.kind === "unsupported-format" || b.kind === "no-locales"
+    p.locales.map((l) => {
+      const own = p.voice(l.code);
+      return [l.code, { text: own ?? conventionalVoice(l.code), fromProject: !!own }];
+    })
   );
   return {
     ready: p.blockers.length === 0,
@@ -4951,27 +5404,18 @@ function build(p) {
     targets: p.targets,
     work: p.work,
     warnings: p.warnings,
+    notes: p.notes,
     blockers: p.blockers,
-    defaults: {
-      voice,
-      keepAsWritten: p.keep,
-      brief: p.hasBrief ? "exists" : "will be drafted"
-    },
-    steps,
-    confirm: blocked ? "" : fixFirst.length ? "start" : "start translating"
+    voice,
+    keepAsWritten: p.keep,
+    brief: p.brief
   };
 }
 async function start(fs, cwd, opts) {
   const locales = opts.locales.map(resolveLocale);
   if (locales.length === 0) throw new UserError("Say which languages to translate into");
   const root = path16.resolve(cwd);
-  const result = {
-    config: "",
-    createdConfig: false,
-    addedLocales: [],
-    wrote: [],
-    warnings: []
-  };
+  const result = { config: "", createdConfig: false, addedLocales: [], warnings: [] };
   let existing;
   try {
     existing = (await loadConfig(fs, root)).file;
@@ -4981,49 +5425,30 @@ async function start(fs, cwd, opts) {
   if (existing) {
     result.config = existing;
     result.addedLocales = (await addLocales(fs, existing, locales)).added;
-  } else {
-    const out = [];
-    const code = await runInit(
-      fs,
-      { cwd: root, yes: true, locales },
-      {
-        interactive: false,
-        log: (l) => out.push(l),
-        error: (l) => out.push(l),
-        ask: async (_q, f) => f
-      }
-    );
-    if (code !== 0) throw new UserError(out.join("\n"));
-    result.config = path16.join(root, CONFIG_FILE);
-    result.createdConfig = true;
-    result.addedLocales = locales;
-    result.warnings = out.filter((l) => l.startsWith("\u25B2 ")).map((l) => l.slice(2));
-  }
-  const project = await openProject(fs, { cwd: root });
-  const dir = project.context.dir;
-  const write2 = async (rel, content) => {
-    const file = path16.join(dir, rel);
-    if (await fs.exists(file)) return;
-    await fs.writeFile(file, content.endsWith("\n") ? content : `${content}
-`);
-    result.wrote.push(rel);
-  };
-  for (const l of projectLocales(project)) {
-    await write2(`${CONTEXT_FILES.voiceDir}/${l}.md`, opts.voice?.[l] ?? defaultVoice(l));
-  }
-  const keep = opts.keepAsWritten ?? await appNames(fs, root, await detect(fs, root));
-  if (keep.length) {
-    await write2(
-      CONTEXT_FILES.glossary,
-      toYaml({ terms: keep.map((term) => ({ term, translate: false })) }, { lineWidth: 0 })
-    );
+    return result;
   }
+  const out = [];
+  const code = await runInit(
+    fs,
+    { cwd: root, yes: true, locales },
+    {
+      interactive: false,
+      log: (l) => out.push(l),
+      error: (l) => out.push(l),
+      ask: async (_q, f) => f
+    }
+  );
+  if (code !== 0) throw new UserError(out.join("\n"));
+  result.config = path16.join(root, CONFIG_FILE);
+  result.createdConfig = true;
+  result.addedLocales = locales;
+  result.warnings = out.filter((l) => l.startsWith("\u25B2 ")).map((l) => l.slice(2));
   return result;
 }
 
 // src/translate/prompt.ts
 var TRANSLATION_RULES = `- Translate the source text of each item into the item's locale. Write what a native speaker would put in a well-made app: natural, concise UI language, not a word-for-word copy.
-- Follow the brief and the locale's voice. Work out where each text appears and what it does from its comment, context, and usage: the code that shows it, whose file path names the screen and whose code shows whether it is a button, title, label, hint or message.
+- Follow the brief and the locale's voice (defaultVoice when the project has set none: the usual convention for that language). Work out where each text appears and what it does from its comment, context, and usage: the code that shows it, whose file path names the screen and whose code shows whether it is a button, title, label, hint or message.
 - Keep every placeholder exactly as written (%s, %1$s, %d, %@, {name}, %(count)d\u2026). You may move them to fit the grammar; numbered ones (%1$s) may be reordered freely.
 - Keep markup and escapes exactly: tags such as <b> or <xliff:g>, entities, \\n, and any leading or trailing spaces and newlines.
 - Glossary: a term marked keep stays exactly as written; a term with use must be translated that way.
@@ -5073,6 +5498,9 @@ function extractJson(reply) {
   }
 }
 
+// src/translate/translate.ts
+import { setTimeout as delay } from "timers/promises";
+
 // src/translate/providers.ts
 var BUILT_IN = {
   anthropic: {
@@ -5109,6 +5537,10 @@ function createCompletion(spec, opts = {}) {
   const { provider, model } = parseModel(spec);
   const env = opts.env ?? process.env;
   const doFetch = opts.fetch ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
+    throw new UserError("timeoutMs must be a positive integer no greater than 2147483647");
+  }
   const custom = opts.custom?.[provider];
   const builtIn = BUILT_IN[provider];
   if (!custom && !builtIn) {
@@ -5123,30 +5555,44 @@ function createCompletion(spec, opts = {}) {
   if (keyNames.length > 0 && !apiKey) {
     throw new UserError(`Set ${keyNames[0]} to use ${provider} models.`);
   }
-  const post = async (url, headers, body) => {
-    let res;
+  const post = async (url, headers, body, external) => {
+    const deadline = new AbortController();
+    const signal = external ? AbortSignal.any([external, deadline.signal]) : deadline.signal;
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
     try {
-      res = await doFetch(url, {
+      signal.throwIfAborted();
+      const res = await doFetch(url, {
         method: "POST",
         headers: { "content-type": "application/json", ...headers },
-        body: JSON.stringify(body)
+        body: JSON.stringify(body),
+        signal
       });
+      const text = await res.text();
+      signal.throwIfAborted();
+      if (!res.ok) {
+        throw new ProviderError(
+          `${provider} returned ${res.status}: ${text.slice(0, 500)}`,
+          res.status === 429 || res.status >= 500
+        );
+      }
+      try {
+        return JSON.parse(text);
+      } catch {
+        throw new ProviderError(
+          `${provider} returned something that isn't JSON: ${text.slice(0, 200)}`
+        );
+      }
     } catch (e) {
+      if (external?.aborted) throw new UserError("Translation cancelled");
+      if (deadline.signal.aborted) {
+        throw new ProviderError(
+          `${provider}: request timed out after ${timeoutMs} ms; retry or increase --timeout-ms`
+        );
+      }
+      if (e instanceof ProviderError) throw e;
       throw new ProviderError(`${provider}: could not reach ${baseUrl} (${e.message})`);
-    }
-    const text = await res.text();
-    if (!res.ok) {
-      throw new ProviderError(
-        `${provider} returned ${res.status}: ${text.slice(0, 500)}`,
-        res.status === 429 || res.status >= 500
-      );
-    }
-    try {
-      return JSON.parse(text);
-    } catch {
-      throw new ProviderError(
-        `${provider} returned something that isn't JSON: ${text.slice(0, 200)}`
-      );
+    } finally {
+      clearTimeout(timer);
     }
   };
   if (protocol === "anthropic") {
@@ -5159,7 +5605,8 @@ function createCompletion(spec, opts = {}) {
           max_tokens: req.maxTokens ?? 16e3,
           system: req.system,
           messages: [{ role: "user", content: req.user }]
-        }
+        },
+        req.signal
       );
       if (data.stop_reason === "max_tokens") {
         throw new ProviderError(`${provider}: the response was cut off; use a smaller batch`);
@@ -5178,7 +5625,8 @@ function createCompletion(spec, opts = {}) {
           { role: "system", content: req.system },
           { role: "user", content: req.user }
         ]
-      }
+      },
+      req.signal
     );
     const choice = data.choices?.[0];
     if (choice?.finish_reason === "length") {
@@ -5208,15 +5656,38 @@ function modelFor(project, locale2, override) {
   return model;
 }
 async function translateProject(start2, opts = {}) {
+  const controller = new AbortController();
+  const signal = opts.signal ? AbortSignal.any([opts.signal, controller.signal]) : controller.signal;
+  try {
+    return await runTranslation(start2, { ...opts, signal });
+  } finally {
+    controller.abort();
+  }
+}
+async function runTranslation(start2, opts) {
+  const checkCancelled = () => {
+    if (opts.signal?.aborted) throw new UserError("Translation cancelled");
+  };
+  checkCancelled();
   const log = opts.log ?? (() => {
   });
   const locales = opts.locales ?? projectLocales(start2);
   if (locales.length === 0)
     throw new UserError("No locales to translate. Add `locales:` to the config.");
   const batchSize = opts.batchSize ?? 30;
-  const concurrency = Math.max(1, opts.concurrency ?? 4);
-  const maxAttempts = Math.max(1, opts.attempts ?? 2);
-  const makeCompletion = opts.completion ?? ((model) => createCompletion(model, { custom: start2.config.providers }));
+  const concurrency = opts.concurrency ?? 4;
+  const maxAttempts = opts.attempts ?? 2;
+  const maxPromptBytes = opts.maxPromptBytes ?? 48e3;
+  for (const [name, value] of Object.entries({
+    batchSize,
+    concurrency,
+    attempts: maxAttempts,
+    maxPromptBytes
+  })) {
+    if (!Number.isSafeInteger(value) || value < 1)
+      throw new UserError(`${name} must be a positive integer`);
+  }
+  const makeCompletion = opts.completion ?? ((model) => createCompletion(model, { custom: start2.config.providers, timeoutMs: opts.timeoutMs }));
   const models = Object.fromEntries(locales.map((l) => [l, modelFor(start2, l, opts.model)]));
   const clients = /* @__PURE__ */ new Map();
   const client = (model) => {
@@ -5238,9 +5709,11 @@ async function translateProject(start2, opts = {}) {
   const files = /* @__PURE__ */ new Set();
   const tries = /* @__PURE__ */ new Map();
   const givenUp = /* @__PURE__ */ new Set();
+  const finished = /* @__PURE__ */ new Set();
   let project = start2;
   const usages = await buildUsageIndex(start2);
   for (; ; ) {
+    checkCancelled();
     const round = [];
     for (const locale2 of locales) {
       let offset = 0;
@@ -5252,34 +5725,42 @@ async function translateProject(start2, opts = {}) {
           states: opts.states,
           limit: batchSize,
           offset,
-          skip: givenUp,
+          skip: finished,
           usages,
           skipHandEdited: !opts.force
         });
         if (batch.items.length === 0) break;
-        round.push(batch);
+        const retries = /* @__PURE__ */ new Map();
+        for (const item of batch.items) {
+          const retry = tries.get(itemId(item));
+          if (retry) retries.set(item, { value: retry.value, errors: retry.errors });
+        }
+        let user = userPrompt(batch, retries);
+        while (Buffer.byteLength(systemPrompt()) + Buffer.byteLength(user) > maxPromptBytes) {
+          if (batch.items.length === 1) {
+            const item = batch.items[0];
+            throw new UserError(
+              `Prompt for ${item.locale}:${item.key} exceeds maxPromptBytes (${maxPromptBytes}); shorten context or increase --max-prompt-bytes`
+            );
+          }
+          batch.items.pop();
+          user = userPrompt(batch, retries);
+        }
+        round.push({ batch, user });
         offset += batch.items.length;
       }
       if (round.length >= concurrency) break;
     }
     if (round.length === 0) break;
     const replies = await Promise.all(
-      round.map(async (batch) => {
+      round.map(async ({ batch, user }) => {
         const locale2 = batch.items[0]?.locale;
         const model = models[locale2];
-        const retries = /* @__PURE__ */ new Map();
-        for (const item of batch.items) {
-          const t = tries.get(itemId(item));
-          if (t)
-            retries.set(item, {
-              ...t.value !== void 0 ? { value: t.value } : {},
-              errors: t.errors
-            });
-        }
         log(`${locale2}: translating ${batch.items.length} strings with ${model}\u2026`);
         try {
           const reply = await callWithRetry(
-            () => client(model)({ system: systemPrompt(), user: userPrompt(batch, retries) })
+            () => client(model)({ system: systemPrompt(), user, signal: opts.signal }),
+            opts.signal
           );
           return { batch, model, reply };
         } catch (e) {
@@ -5289,12 +5770,16 @@ async function translateProject(start2, opts = {}) {
       })
     );
     for (const { batch, model, reply, error } of replies) {
+      checkCancelled();
       const byId = new Map(batch.items.map((i) => [itemId(i), i]));
       const fail = (item, errors, value) => {
         const id2 = itemId(item);
         const count = (tries.get(id2)?.count ?? 0) + 1;
         tries.set(id2, { count, errors, item, ...value !== void 0 ? { value } : {} });
-        if (count >= maxAttempts) givenUp.add(id2);
+        if (count >= maxAttempts) {
+          givenUp.add(id2);
+          finished.add(id2);
+        }
       };
       if (error !== void 0) {
         throw new UserError(error);
@@ -5325,12 +5810,20 @@ async function translateProject(start2, opts = {}) {
       const r = await submit(
         project,
         answers.map((a) => a.sub),
-        { model, force: opts.force }
+        {
+          model,
+          force: opts.force,
+          usages,
+          expectedSources: new Map(batch.items.map((item) => [itemId(item), item.source]))
+        }
       );
       for (const f of r.files) files.add(f);
       result.translated += r.accepted.length;
       const accepted = new Set(r.accepted.map((a) => itemId(a)));
-      for (const id2 of accepted) tries.delete(id2);
+      for (const id2 of accepted) {
+        tries.delete(id2);
+        finished.add(id2);
+      }
       for (const { item, sub } of answers) {
         const id2 = itemId(item);
         if (accepted.has(id2)) continue;
@@ -5365,15 +5858,21 @@ async function translateProject(start2, opts = {}) {
     });
     result.heldForReview = held.items.filter((i) => i.editedByHand).map(({ target, locale: locale2, key }) => ({ target, locale: locale2, key }));
   }
+  checkCancelled();
   return result;
 }
-async function callWithRetry(fn, tries = 3) {
+async function callWithRetry(fn, signal, tries = 3) {
   for (let i = 1; ; i++) {
+    if (signal?.aborted) throw new UserError("Translation cancelled");
     try {
       return await fn();
     } catch (e) {
       if (!(e instanceof ProviderError) || !e.transient || i >= tries) throw e;
-      await new Promise((r) => setTimeout(r, 1e3 * 2 ** i));
+      try {
+        await delay(1e3 * 2 ** i, void 0, { signal });
+      } catch {
+        throw new UserError("Translation cancelled");
+      }
     }
   }
 }
@@ -5400,6 +5899,7 @@ export {
   printApprove,
   printPlan,
   runInit,
+  buildUsageIndex,
   validateProject,
   nextBatch,
   SubmissionSchema,
@@ -5413,4 +5913,4 @@ export {
   TRANSLATION_RULES,
   translateProject
 };
-//# sourceMappingURL=chunk-OWT47JBL.js.map
+//# sourceMappingURL=chunk-GNL5EFNP.js.map