prosebook 0.1.0 → 0.3.0

package/src/tools/native/swift.ts

@@ -0,0 +1,326 @@
+/**
+ * The model as a Swift file: a `String`-backed enum of locales with a property or method per
+ * message, and a file-private enum holding what formats them.
+ */
+import type { NativeTarget } from '#src/tools/config.ts';
+import { camel, checkNames, conditionCode, float, leading, stringLiteral, wordsOf } from './emit.ts';
+import type { NativeMessage, NativeModel, Part } from './model.ts';
+import type { NumberSpec } from './number.ts';
+
+const KEYWORDS = new Set(
+  'associatedtype class deinit enum extension fileprivate func import init inout internal let open operator private precedencegroup protocol public rethrows static struct subscript typealias var break case catch continue default defer do else fallthrough for guard if in repeat return throw switch where while Any as await false is nil self Self super throws true try'.split(
+    ' ',
+  ),
+);
+
+const ident = (name: string) => (KEYWORDS.has(name) ? `\`${name}\`` : name);
+const lit = (value: string) => stringLiteral(value, 'swift');
+const caseName = (tag: string) => ident(leading(camel(wordsOf(tag))));
+const argName = (name: string) => ident(leading(camel(wordsOf(name))));
+
+function doc(lines: string[], indent: string): string {
+  return lines.map((l) => (l === '' ? `${indent}///\n` : `${indent}/// ${l}\n`)).join('');
+}
+
+/** The parts as an expression of type `String`, with `rt` the runtime enum. */
+function expr(parts: Part[], indent: string, rt: string): string {
+  if (parts.length === 0) return '""';
+  const values = parts.map((p) => (p.type === 'text' ? lit(p.value) : value(p, indent, rt)));
+  return values.length === 1 ? values[0]! : `[${values.join(', ')}].joined()`;
+}
+
+function value(part: Exclude<Part, { type: 'text' }>, indent: string, rt: string): string {
+  const inner = `${indent}    `;
+  if (part.type === 'string') return argName(part.arg);
+  if (part.type === 'number') {
+    const of = part.offset === 0 ? argName(part.arg) : `${argName(part.arg)} - ${float(part.offset)}`;
+    return `${rt}.number(${of}, ${rt}.f${part.format}, ${lit(part.fallback)})`;
+  }
+  if (part.type === 'select') {
+    const arms = part.arms.map((a) => `${inner}case ${lit(a.key)}: return ${expr(a.parts, inner, rt)}\n`).join('');
+    return `{ () -> String in\n${inner}switch ${argName(part.arg)} {\n${arms}${inner}default: return ${expr(part.other, inner, rt)}\n${inner}}\n${indent}}()`;
+  }
+  // A plural, the one kind left. With only `other`, there is nothing to select on.
+  if (part.arms.length + part.exact.length === 0) return expr(part.other, indent, rt);
+  const arg = argName(part.arg);
+  const on = part.on === 'round' ? `${rt}.round(${arg})` : part.on === 'percent' ? `${arg} * 100.0` : arg;
+  const { minFrac, maxFrac } = part.rounding;
+  const exact = part.exact.map((e) => `(${float(e.value)}, ${lit(`=${e.value}`)})`).join(', ');
+  const arms = [...part.exact.map((e) => ({ key: `=${e.value}`, parts: e.parts })), ...part.arms]
+    .map((a) => `${inner}case ${lit(a.key)}: return ${expr(a.parts, inner, rt)}\n`)
+    .join('');
+  const pick = `${rt}.plural(${on}, ${float(part.offset)}, [${exact}], ${rt}.r${part.rules}, ${minFrac}, ${maxFrac})`;
+  return `{ () -> String in\n${inner}switch ${pick} {\n${arms}${inner}default: return ${expr(part.other, inner, rt)}\n${inner}}\n${indent}}()`;
+}
+
+/** The protocol a number argument takes, and the property that reads it as a `Double`. */
+interface NumberProtocol {
+  type: string;
+  value: string;
+}
+
+function member(m: NativeMessage, name: string, rt: string, number: NumberProtocol): string {
+  const cases = (render: (parts: Part[]) => string) =>
+    m.bodies.map((b) => `        case ${b.locales.map((l) => `.${caseName(l)}`).join(', ')}: return ${render(b.parts)}\n`).join('');
+  const argDocs = m.args.filter((a) => a.doc !== undefined).map((a) => `- ${argName(a.name)}: ${a.doc}`);
+  const head = doc(argDocs.length > 0 ? [...m.doc, '', ...argDocs] : m.doc, '    ');
+  const body = `        switch self {\n${cases((parts) => expr(parts, '        ', rt))}        }\n`;
+  if (m.args.length === 0) return `${head}    public var ${name}: String {\n${body}    }\n`;
+  const params = m.args.map((a) => `${argName(a.name)}: ${a.type === 'number' ? `some ${number.type}` : 'String'}`).join(', ');
+  const numbers = m.args
+    .filter((a) => a.type === 'number')
+    .map((a) => `        let ${argName(a.name)} = ${argName(a.name)}.${number.value}\n`)
+    .join('');
+  return `${head}    public func ${name}(${params}) -> String {\n${numbers}${body}    }\n`;
+}
+
+function formatConst(spec: NumberSpec, i: number): string {
+  const affix = ([prefix, suffix]: readonly [string, string]) => `(${lit(prefix)}, ${lit(suffix)})`;
+  const fields = [
+    `minInt: ${spec.minInt}`,
+    `minFrac: ${spec.minFrac}`,
+    `maxFrac: ${spec.maxFrac}`,
+    `shift: ${spec.shift}`,
+    `primary: ${spec.grouping.primary}`,
+    `secondary: ${spec.grouping.secondary}`,
+    `minGroup: ${spec.grouping.min}`,
+    `decimal: ${lit(spec.decimal)}`,
+    `group: ${lit(spec.group)}`,
+    `digits: ${spec.digits === undefined ? 'nil' : `[${spec.digits.map(lit).join(', ')}]`}`,
+    `positive: ${affix(spec.positive)}`,
+    `negative: ${affix(spec.negative)}`,
+    `zero: ${affix(spec.zero)}`,
+    `negativeZero: ${affix(spec.negativeZero)}`,
+    `infinity: ${lit(spec.infinity)}`,
+    `negativeInfinity: ${lit(spec.negativeInfinity)}`,
+  ];
+  return `    static let f${i} = Format(\n${fields.map((f) => `        ${f}`).join(',\n')}\n    )\n`;
+}
+
+const NUMBER = `
+    /// A number format, taken apart when the file was generated.
+    struct Format {
+        let minInt: Int
+        let minFrac: Int
+        let maxFrac: Int
+        let shift: Int
+        let primary: Int
+        let secondary: Int
+        let minGroup: Int
+        let decimal: String
+        let group: String
+        let digits: [String]?
+        let positive: (String, String)
+        let negative: (String, String)
+        let zero: (String, String)
+        let negativeZero: (String, String)
+        let infinity: String
+        let negativeInfinity: String
+    }
+
+    /// \`value\` as \`format\` writes it, or \`fallback\` where it isn't a number.
+    static func number(_ value: Double, _ format: Format, _ fallback: String) -> String {
+        if value.isNaN { return fallback }
+        if value.isInfinite { return value > 0 ? format.infinity : format.negativeInfinity }
+        let (written, frac) = digits(abs(value), format.shift, format.minFrac, format.maxFrac)
+        var int = written
+        let zero = (written + frac).allSatisfy { $0 == "0" }
+        let negative = value.sign == .minus
+        let (prefix, suffix) = zero ? (negative ? format.negativeZero : format.zero) : (negative ? format.negative : format.positive)
+        while int.count < max(format.minInt, 1) { int = "0" + int }
+        let grouped = format.minGroup > 0 && int.count >= format.primary + format.minGroup
+        var out = prefix
+        for (i, digit) in int.enumerated() {
+            let left = int.count - i
+            if grouped && i > 0 && (left == format.primary || (left > format.primary && (left - format.primary) % format.secondary == 0)) {
+                out += format.group
+            }
+            out += shown(digit, format)
+        }
+        if !frac.isEmpty {
+            out += format.decimal
+            for digit in frac { out += shown(digit, format) }
+        }
+        return out + suffix
+    }
+
+    private static func shown(_ digit: Character, _ format: Format) -> String {
+        guard let digits = format.digits, let ascii = digit.asciiValue else { return String(digit) }
+        return digits[Int(ascii - 48)]
+    }
+
+    /// The shortest digits that read back as \`value\`, as \`Intl\` rounds them: moved \`shift\` places
+    /// right, rounded half away from zero to \`max\` fraction digits, and trailing zeros cut to \`min\`.
+    static func digits(_ value: Double, _ shift: Int, _ min: Int, _ max: Int) -> (String, String) {
+        // \`description\` writes the shortest digits that read back, with an exponent past a size.
+        let written = value.description.split(separator: "e", maxSplits: 1).map(String.init)
+        let exponent = written.count > 1 ? Int(written[1]) ?? 0 : 0
+        let pieces = written[0].split(separator: ".", maxSplits: 1, omittingEmptySubsequences: false).map(String.init)
+        var all = (pieces[0] + (pieces.count > 1 ? pieces[1] : "")).compactMap { $0.wholeNumberValue }
+        var point = pieces[0].count + exponent + shift
+        if point < 0 {
+            all = Array(repeating: 0, count: -point) + all
+            point = 0
+        }
+        while all.count <= point + max { all.append(0) }
+        let next = all[point + max]
+        all = Array(all.prefix(point + max))
+        if next >= 5 {
+            var at = all.count - 1
+            while at >= 0 && all[at] == 9 {
+                all[at] = 0
+                at -= 1
+            }
+            if at < 0 {
+                all.insert(1, at: 0)
+                point += 1
+            } else {
+                all[at] += 1
+            }
+        }
+        var frac = Array(all[point...])
+        while frac.count > min && frac.last == 0 { frac.removeLast() }
+        let int = all[..<point].drop(while: { $0 == 0 })
+        return (int.map(String.init).joined(), frac.map(String.init).joined())
+    }
+`;
+
+const PLURAL = `
+    /// CLDR's plural operands of a number as written.
+    struct Operands {
+        let n: Double
+        let i: Double
+        let v: Double
+        let w: Double
+        let f: Double
+        let t: Double
+        let c: Double
+        let e: Double
+    }
+
+    /// The arm a plural takes: the \`=N\` that \`value\` equals, else the category of \`value\` less \`offset\`.
+    static func plural(
+        _ value: Double, _ offset: Double, _ exact: [(Double, String)], _ rules: (Operands) -> String, _ min: Int, _ max: Int
+    ) -> String {
+        exact.first(where: { $0.0 == value })?.1 ?? category(rules, value - offset, min, max)
+    }
+
+    /// The category \`rules\` give \`value\`, rounded to between \`min\` and \`max\` fraction digits.
+    private static func category(_ rules: (Operands) -> String, _ value: Double, _ min: Int, _ max: Int) -> String {
+        guard value.isFinite else { return "other" }
+        let (written, frac) = digits(abs(value), 0, min, max)
+        let int = written.isEmpty ? "0" : written
+        var trimmed = Substring(frac)
+        while trimmed.last == "0" { trimmed.removeLast() }
+        let read = { (s: String) in Double(s) ?? 0 }
+        return rules(Operands(
+            n: read(frac.isEmpty ? int : int + "." + frac),
+            i: read(int),
+            v: Double(frac.count),
+            w: Double(trimmed.count),
+            f: read(frac),
+            t: read(String(trimmed)),
+            c: 0,
+            e: 0
+        ))
+    }
+
+    /// An integer in the range, as CLDR's ranges hold.
+    private static func within(_ value: Double, _ from: Double, _ to: Double) -> Bool {
+        value.truncatingRemainder(dividingBy: 1) == 0 && value >= from && value <= to
+    }
+
+    /// \`Math.round\`: half up, toward positive infinity.
+    static func round(_ value: Double) -> Double {
+        let floor = value.rounded(.down)
+        return value - floor >= 0.5 ? floor + 1 : floor
+    }
+`;
+
+const NUMBER_TYPES = [
+  'Int',
+  'Int8',
+  'Int16',
+  'Int32',
+  'Int64',
+  'UInt',
+  'UInt8',
+  'UInt16',
+  'UInt32',
+  'UInt64',
+  'Double',
+  'Float',
+  'CGFloat',
+];
+
+export function swiftFile(model: NativeModel, target: NativeTarget & { name: string }, banner: string): string {
+  const name = target.name;
+  const rt = `${name}Runtime`;
+  const names = model.messages.map((m): [string, string] => [m.key, ident(leading(camel(m.words)))]);
+  checkNames('swift', names, ['tag', 'source', 'negotiate', 'rawValue', 'allCases', 'hashValue']);
+  const cases = model.locales
+    .map((l) => `    /// \`${l}\`${l === model.source ? ', the source' : ''}.\n    case ${caseName(l)} = ${lit(l)}\n`)
+    .join('');
+  // Named after the type, so two generated files in one module don't both add a property to `Int`.
+  const number = { type: `${name}Number`, value: `${name.charAt(0).toLowerCase()}${name.slice(1)}Value` };
+  const members = model.messages.map((m, i) => member(m, names[i]![1], rt, number)).join('\n');
+  const usesNumbers = model.messages.some((m) => m.args.some((a) => a.type === 'number'));
+  const numberProtocol = !usesNumbers
+    ? ''
+    : `
+/// A number a message formats: any of Swift's integers or floats.
+public protocol ${number.type} {
+    var ${number.value}: Double { get }
+}
+
+${NUMBER_TYPES.map((t) => `extension ${t}: ${number.type} { public var ${number.value}: Double { Double(self) } }`).join('\n')}
+`;
+  const rules = model.rules
+    .map(({ name: rule, rules }, i) => {
+      const checks = rules.map(
+        ([category, condition]) =>
+          `        if ${conditionCode(condition, { field: (op) => `o.${op}`, mod: (v, by) => `${v}.truncatingRemainder(dividingBy: ${by})`, within: (v, from, to) => `within(${v}, ${from}, ${to})` })} { return ${lit(category)} }\n`,
+      );
+      return `    /// ${rule}\n    static func r${i}(_ o: Operands) -> String {\n${checks.join('')}        return "other"\n    }\n`;
+    })
+    .join('\n');
+  const runtime =
+    model.formats.length + model.rules.length === 0
+      ? ''
+      : `
+/// What formats the messages, generated with them.
+private enum ${rt} {${NUMBER}${model.rules.length > 0 ? PLURAL : ''}
+${model.formats.map(formatConst).join('\n')}${rules === '' ? '' : `\n${rules}`}}
+`;
+
+  return `${banner}
+import Foundation
+${numberProtocol}
+/// A locale the catalog is written or translated in, and its messages.
+public enum ${name}: String, CaseIterable, Sendable {
+${cases}
+    /// The locale the catalog is written in, which every message falls back to.
+    public static let source: ${name} = .${caseName(model.source)}
+
+    /// The locale's BCP 47 tag.
+    public var tag: String { rawValue }
+
+    /// The best locale for what was asked, most preferred first: each tag tries an exact match, then
+    /// its parents (\`pt-BR\` finds \`pt\`), then any locale of its language. The source if none is.
+    public static func negotiate(_ requested: [String]) -> ${name} {
+        let language = { (tag: String) in tag.split(separator: "-").first.map { $0.lowercased() } ?? "" }
+        for want in requested {
+            var tag = want
+            while true {
+                if let found = allCases.first(where: { $0.tag.lowercased() == tag.lowercased() }) { return found }
+                guard let cut = tag.lastIndex(of: "-") else { break }
+                tag = String(tag[..<cut])
+            }
+            if let found = allCases.first(where: { language($0.tag) == language(want) }) { return found }
+        }
+        return source
+    }
+
+${members}}
+${runtime}`;
+}

package/src/tools/scan.ts

@@ -81,10 +81,8 @@ export function looksLikeCode(text: string): boolean {
 const NON_PROSE_ELEMENTS = new Set(['code', 'pre', 'kbd', 'samp', 'script', 'style', 'svg', 'path']);
 const LETTER = /\p{L}/u;
 
-/** Literal text in JSX that a person reads, where it should be a catalog entry. */
-export function hardcodedText(file: string, code: string, attributes: string[]): Hardcoded[] {
-  const { program } = parseSync(file, code);
-  const found: Hardcoded[] = [];
+/** Offsets in `code` as lines and columns, and whether a line is marked `prosebook-ignore`, on it or the line above. */
+function lineIndex(code: string) {
   const lines = code.split('\n');
   const lineStarts: number[] = [];
   let offset = 0;
@@ -104,6 +102,14 @@ export function hardcodedText(file: string, code: string, attributes: string[]):
   };
   const ignored = (line: number) =>
     (lines[line - 1] ?? '').includes('prosebook-ignore') || (lines[line - 2] ?? '').includes('prosebook-ignore');
+  return { position, ignored };
+}
+
+/** Literal text in JSX that a person reads, where it should be a catalog entry. */
+export function hardcodedText(file: string, code: string, attributes: string[]): Hardcoded[] {
+  const { program } = parseSync(file, code);
+  const found: Hardcoded[] = [];
+  const { position, ignored } = lineIndex(code);
   const report = (node: Node, text: string, where: string) => {
     const trimmed = text.replace(/\s+/g, ' ').trim();
     if (!LETTER.test(trimmed) || looksLikeCode(trimmed)) return;
@@ -171,3 +177,127 @@ export function scan(dirs: string[], extensions: string[], attributes: string[],
   }
   return { hardcoded, refs, files: files.length };
 }
+
+/** A copy's methods that take a key first. */
+export const READERS = new Set(['t', 'rich']);
+
+export interface UnseenRead {
+  file: string;
+  line: number;
+  column: number;
+  /** The read as written, on one line. */
+  code: string;
+  /** What it calls: a reader, the name it was imported by, or `Text`. */
+  name: string;
+}
+
+export interface Reads {
+  /** Reads whose key a build can't see, in calls that may be to a copy's `t` or `rich`. */
+  unseen: UnseenRead[];
+  /** Names a copy's readers are bound to here, as in `const { rich: tRich } = copy`. */
+  aliases: Set<string>;
+}
+
+const PREFIX = /^[a-z0-9][\w-]*(?:\.[\w-]+)*\.$/;
+const WRAPPERS = new Set(['ParenthesizedExpression', 'TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'TSTypeAssertion']);
+
+/** Whether `keyRefs` finds every key an expression can be: a literal, or a template or sum after a key prefix. */
+function keySeen(node: Node | undefined): boolean {
+  if (node === undefined) return false;
+  if (WRAPPERS.has(node.type)) return keySeen(node.expression as Node);
+  switch (node.type) {
+    case 'Literal':
+      return typeof node.value === 'string';
+    case 'TemplateLiteral': {
+      const [head] = node.quasis as { value: { cooked: string | null } }[];
+      return (node.expressions as Node[]).length === 0 || PREFIX.test(head?.value.cooked ?? '');
+    }
+    case 'BinaryExpression': {
+      const left = node.left as Node;
+      return node.operator === '+' && left.type === 'Literal' && typeof left.value === 'string' && PREFIX.test(left.value);
+    }
+    case 'ConditionalExpression':
+      return keySeen(node.consequent as Node) && keySeen(node.alternate as Node);
+    case 'LogicalExpression':
+      return keySeen(node.left as Node) && keySeen(node.right as Node);
+    default:
+      return false;
+  }
+}
+
+const nameOf = (node: Node | undefined): string | undefined =>
+  node?.type === 'Identifier' || node?.type === 'JSXIdentifier'
+    ? (node.name as string)
+    : node?.type === 'Literal'
+      ? String(node.value)
+      : undefined;
+
+/**
+ * The reads in a module whose key a pruned build can't see, as in `t(item.key)` or `<Text id={id} />`:
+ * the build would leave the message out, and the key would show in its place. A build has no types,
+ * so readers are known by name: `t` and `rich` called alone or as methods, and any name imported here,
+ * which may be bound to one elsewhere (`aliases`); the caller keeps those whose name turns out to be a
+ * reader. `<Text>` counts where it is imported from `prosebook/react`. Lines marked `prosebook-ignore`
+ * are skipped.
+ */
+export function unseenReads(file: string, code: string): Reads {
+  const { program } = parseSync(file, code);
+  const { position, ignored } = lineIndex(code);
+  const unseen: UnseenRead[] = [];
+  const aliases = new Set<string>();
+  /** Local name to the name it was imported by. */
+  const imported = new Map<string, string>();
+  const texts = new Set<string>();
+  for (const statement of (program as unknown as Node).body as Node[]) {
+    if (statement.type !== 'ImportDeclaration') continue;
+    for (const s of statement.specifiers as Node[]) {
+      const name = s.type === 'ImportSpecifier' ? nameOf(s.imported as Node) : undefined;
+      const local = nameOf(s.local as Node);
+      if (name === undefined || local === undefined) continue;
+      if (name === 'Text' && (statement.source as Node).value === 'prosebook/react') texts.add(local);
+      else imported.set(local, name);
+    }
+  }
+  const report = (node: Node, name: string) => {
+    const at = position(node.start);
+    if (ignored(at.line)) return;
+    const text = code.slice(node.start, node.end).replace(/\s+/g, ' ');
+    unseen.push({ file, ...at, name, code: text.length > 80 ? `${text.slice(0, 77)}...` : text });
+  };
+  // Calls by a plain name, kept until every alias in the module is known.
+  const calls: [Node, string][] = [];
+  const visit = (node: Node) => {
+    if (node.type === 'ObjectPattern') {
+      for (const p of node.properties as Node[]) {
+        if (p.type === 'Property' && READERS.has(nameOf(p.key as Node) ?? '') && (p.value as Node).type === 'Identifier')
+          aliases.add(nameOf(p.value as Node)!);
+      }
+    }
+    if (node.type === 'CallExpression' && !keySeen((node.arguments as Node[])[0])) {
+      const callee = node.callee as Node;
+      if (callee.type === 'Identifier') calls.push([node, callee.name as string]);
+      else if (callee.type === 'MemberExpression' && !callee.computed && READERS.has(nameOf(callee.property as Node) ?? ''))
+        report(node, nameOf(callee.property as Node)!);
+    }
+    if (node.type === 'JSXOpeningElement' && texts.has(nameOf(node.name as Node) ?? '')) {
+      const id = (node.attributes as Node[]).find((a) => a.type === 'JSXAttribute' && nameOf(a.name as Node) === 'id');
+      const value = id?.value as Node | null | undefined;
+      if (value !== null && value !== undefined && !keySeen(value.type === 'JSXExpressionContainer' ? (value.expression as Node) : value))
+        report(node, 'Text');
+    }
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (const child of value) if (isNode(child)) visit(child);
+      } else if (isNode(value)) {
+        visit(value);
+      }
+    }
+  };
+  visit(program as unknown as Node);
+  for (const [node, local] of calls) {
+    if (READERS.has(local) || aliases.has(local)) report(node, local);
+    else if (imported.has(local)) report(node, imported.get(local)!);
+  }
+  unseen.sort((a, b) => (a.line === b.line ? a.column - b.column : a.line - b.line));
+  return { unseen, aliases };
+}

package/src/tools/syntax.ts

@@ -4,7 +4,7 @@
  */
 import { parseMessage, type MessageFormatElement } from './icu.ts';
 import { toMf1 } from './mf1.ts';
-import { parseMf2, toMf2 } from './mf2.ts';
+import { parseMf2, toMf2, type Isolate } from './mf2.ts';
 
 export type MessageFormatVersion = 1 | 2;
 
@@ -14,8 +14,8 @@ export const SYNTAX_NAME: Record<MessageFormatVersion, string> = { 1: 'ICU Messa
  * A message as the element tree. MF2 is read per locale: which variants a value can reach depends
  * on the locale's plural rules (see `matchTree` in mf2.ts).
  */
-export function readMessage(version: MessageFormatVersion, text: string, locale: string): MessageFormatElement[] {
-  return version === 2 ? parseMf2(text, locale) : parseMessage(text);
+export function readMessage(version: MessageFormatVersion, text: string, locale: string, isolate?: Isolate): MessageFormatElement[] {
+  return version === 2 ? parseMf2(text, locale, isolate) : parseMessage(text);
 }
 
 /** A tree as text in the given syntax. Throws, saying what the syntax can't express, where it can't. */

package/src/tools/todo.ts

@@ -0,0 +1,118 @@
+/**
+ * `prosebook todo`: a locale's missing and stale entries, each with what a translator needs above it,
+ * as the YAML to fill in. `prosebook import` reads it back filled.
+ *
+ * With `prompt`, it leads with what a model must be told to reply in that form. prosebook writes the
+ * prompt and checks the reply; which model answers it, and how, is left to whoever runs it.
+ */
+import { stringify } from 'yaml';
+
+import type { Catalog, Message } from './catalog.ts';
+import type { ResolvedConfig } from './config.ts';
+import { TYPE, walk } from './icu.ts';
+import { changeOf, type StaleTranslation } from './lock.ts';
+import { SYNTAX_NAME } from './syntax.ts';
+
+export interface Todo {
+  /** How many entries want a translation. */
+  count: number;
+  /** The entries as YAML, by area, with the prompt first when one was asked for. */
+  text: string;
+}
+
+export function todoOf(
+  config: ResolvedConfig,
+  catalog: Catalog,
+  stale: ReadonlyMap<string, StaleTranslation>,
+  locale: string,
+  prompt = false,
+): Todo {
+  const wanted = catalog.messages.filter((m) => !m.translations.has(locale) || stale.has(m.key));
+  if (wanted.length === 0) return { count: 0, text: `# ${locale} is complete` };
+  const byArea = new Map<string, string[]>();
+  for (const m of wanted) {
+    const lines = byArea.get(m.area) ?? [];
+    lines.push('');
+    if (m.context) lines.push(`# ${m.context}`);
+    const what = [m.kind && `kind: ${m.kind}`, m.surface && `surface: ${m.surface}`].filter(Boolean).join(', ');
+    if (what) lines.push(`# ${what}`);
+    for (const [arg, said] of m.argDocs) lines.push(`#   {${arg}}: ${said}`);
+    lines.push(`# ${config.source}: ${m.text.replaceAll('\n', ' ')}`);
+    const change = stale.get(m.key);
+    if (change !== undefined) lines.push(`# stale, the source changed: ${changeOf(change)}`);
+    lines.push(stringify({ [m.key]: m.translations.get(locale)?.text ?? '' }, { lineWidth: 0 }).trimEnd());
+    byArea.set(m.area, lines);
+  }
+  const entries = [...byArea].map(([area, lines]) => `\n# ── ${area}.yaml ──\n${lines.join('\n')}`).join('\n');
+  const count = wanted.length;
+  if (prompt) {
+    const head = promptFor(
+      config,
+      wanted,
+      locale,
+      wanted.some((m) => stale.has(m.key)),
+    );
+    return { count, text: `${head}\n${entries.trimStart()}\n\`\`\`` };
+  }
+  const head = `# prosebook todo: ${count} entr${count === 1 ? 'y' : 'ies'} for ${locale}. Fill them in, then \`prosebook import ${locale} <this file>\`.`;
+  return { count, text: `${head}\n${entries}` };
+}
+
+function promptFor(config: ResolvedConfig, wanted: Message[], locale: string, anyStale: boolean): string {
+  const mf2 = config.messageFormat === 2;
+  const [target, source] = [nameOf(locale), nameOf(config.source)];
+  const plurals = { cardinal: false, ordinal: false };
+  for (const m of wanted) {
+    walk(m.ast, (el) => {
+      if (el.type === TYPE.plural) plurals[el.pluralType === 'ordinal' ? 'ordinal' : 'cardinal'] = true;
+    });
+  }
+  const categories = (type: Intl.PluralRuleType) => {
+    const forms = new Intl.PluralRules(locale, { type }).resolvedOptions().pluralCategories;
+    return forms.length === 1 ? `only the form ${forms[0]}` : `the forms ${new Intl.ListFormat('en').format(forms)}`;
+  };
+  const exact = mf2 ? '`0`' : '`=0`';
+
+  const rules = [
+    mf2
+      ? `Each message is in MessageFormat 2. Keep every {$placeholder}, every markup tag ({#b}…{/b}) around the same words, and every .input, .local and .match line; translate the text, not the names.`
+      : `Each message is in ICU MessageFormat. Keep every {placeholder}, and every <tag> around the same words; translate the text inside plural and select arms, not the arm or argument names.`,
+    plurals.cardinal &&
+      `A plural in ${target} takes ${categories('cardinal')}: give each its own ${mf2 ? 'variant' : 'arm'}, and keep exact ones such as ${exact} where the ${source} has them.`,
+    plurals.ordinal && `An ordinal in ${target} takes ${categories('ordinal')}.`,
+    'The comments above an entry say where it appears, what kind of string it is, and what each placeholder holds. Hold each to its kind, as described below: a button stays as short as the source.',
+    anyStale &&
+      'An entry marked stale has a translation made from an earlier source. The diff shows what changed in the source ({+added+}, [-removed-]): change the translation only as much as that needs, and give it back unchanged if it still holds.',
+    'Quote a value in single quotes when it starts with { or holds ": ", as YAML needs, and double any single quote inside it.',
+  ].filter((r): r is string => typeof r === 'string');
+
+  const kinds = new Set(wanted.flatMap((m) => (m.kind === undefined ? [] : [m.kind])));
+  const surfaces = new Set(wanted.flatMap((m) => (m.surface === undefined ? [] : [m.surface])));
+  const legend = [
+    ...(kinds.size > 0 ? ['', 'Kinds of string:'] : []),
+    ...[...kinds].map((k) => `- ${k}: ${config.kinds[k]?.doc ?? ''}`),
+    ...(surfaces.size > 0 ? ['', 'Surfaces:'] : []),
+    ...[...surfaces].map((s) => `- ${s}: ${config.surfaces[s] ?? ''}`),
+  ];
+
+  return [
+    `Translate the entries below from ${source} (${config.source}) into ${target} (${locale}). They are the text of an app's interface.`,
+    '',
+    'Reply with one YAML code block holding every key below, each with its translation as the value, and nothing else in the block.',
+    '',
+    ...rules.map((r) => `- ${r}`),
+    ...legend,
+    '',
+    `The entries, in ${SYNTAX_NAME[config.messageFormat]}:`,
+    '',
+    '```yaml',
+  ].join('\n');
+}
+
+function nameOf(locale: string): string {
+  try {
+    return new Intl.DisplayNames(['en'], { type: 'language' }).of(locale) ?? locale;
+  } catch {
+    return locale;
+  }
+}