prosebook 0.4.0 → 0.5.0

package/src/tools/exchange.ts

@@ -0,0 +1,275 @@
+/**
+ * `prosebook export`: a locale's entries as XLIFF 2.0 or JSON, for translation tools, and the reader
+ * `prosebook import` takes every format back through, todo's YAML and a model's reply included.
+ *
+ * Messages travel as their ICU or MF2 text, not as XLIFF's inline codes: a plural or a select has no
+ * inline form, and the tools that take these files read ICU. A unit carries its source as exported, so
+ * a translation of a source that has changed since is refused rather than written as current.
+ */
+import { isMap, isScalar, parseDocument, type YAMLMap } from 'yaml';
+
+import type { Catalog, Message } from './catalog.ts';
+import type { ResolvedConfig } from './config.ts';
+import { changeOf, type StaleTranslation } from './lock.ts';
+import { todoMessages } from './todo.ts';
+
+export type ExchangeFormat = 'xliff' | 'json';
+
+export interface Exported {
+  /** How many entries the file holds. */
+  count: number;
+  text: string;
+}
+
+/**
+ * The entries `todo` would list for `locale`, or every one with `all`, as a file a translation tool
+ * reads. The source locale exports every entry, untranslated, for a tool to take as its source.
+ */
+export function exportOf(
+  config: ResolvedConfig,
+  catalog: Catalog,
+  stale: ReadonlyMap<string, StaleTranslation>,
+  locale: string,
+  format: ExchangeFormat,
+  all = false,
+): Exported {
+  const isSource = locale === config.source;
+  const messages = all || isSource ? catalog.messages : todoMessages(catalog, stale, locale);
+  if (messages.length === 0) return { count: 0, text: '' };
+  const textOf = (m: Message) => (isSource ? m.text : m.translations.get(locale)?.text);
+  if (format === 'json') {
+    const json = JSON.stringify(Object.fromEntries(messages.map((m) => [m.key, textOf(m) ?? ''])), null, 2);
+    return { count: messages.length, text: `${json}\n` };
+  }
+
+  const byArea = new Map<string, Message[]>();
+  for (const m of messages) byArea.set(m.area, [...(byArea.get(m.area) ?? []), m]);
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="${escape(config.source)}"${isSource ? '' : ` trgLang="${escape(locale)}"`}>`,
+  ];
+  for (const [area, list] of byArea) {
+    // Newlines and runs of spaces in a message are its own, which a tool may not normalize away.
+    lines.push(`  <file id="${escape(area)}" original="${escape(list[0]!.file)}" xml:space="preserve">`);
+    for (const m of list) {
+      lines.push(`    <unit id="${m.key}">`);
+      const notes = [
+        ['context', m.context],
+        ['kind', m.kind],
+        ['surface', m.surface],
+        ...[...m.argDocs].map(([arg, said]) => ['placeholder', `{${arg}}: ${said}`]),
+        ['stale', isSource || !stale.has(m.key) ? undefined : `the source changed: ${changeOf(stale.get(m.key)!)}`],
+      ].filter((n): n is [string, string] => n[1] !== undefined);
+      if (notes.length > 0) {
+        lines.push('      <notes>');
+        for (const [category, text] of notes) lines.push(`        <note category="${category}">${escape(text)}</note>`);
+        lines.push('      </notes>');
+      }
+      const target = textOf(m);
+      // A stale translation goes out as `initial`: given back as `translated`, someone looked at it.
+      const state = isSource ? '' : ` state="${target === undefined || stale.has(m.key) ? 'initial' : 'translated'}"`;
+      lines.push(`      <segment${state}>`, `        <source>${escape(m.text)}</source>`);
+      if (!isSource && target !== undefined) lines.push(`        <target>${escape(target)}</target>`);
+      lines.push('      </segment>', '    </unit>');
+    }
+    lines.push('  </file>');
+  }
+  lines.push('</xliff>');
+  return { count: messages.length, text: `${lines.join('\n')}\n` };
+}
+
+/** A translation as a file gives it back, before it is checked against the catalog. */
+export interface Returned {
+  key: string;
+  /** Null or empty is left for later. Anything but text or a number is refused. */
+  value: unknown;
+  /** Someone looked at it, so one given back unchanged still holds. A YAML or JSON reply always has. */
+  checked: boolean;
+  /** The source it was made from, where the file says. */
+  source?: string;
+  /** Why the file's entry can't be read, which leaves it out. */
+  problem?: string;
+}
+
+/**
+ * The translations in a file `import` was given: XLIFF 2.0 when it starts as XML, otherwise YAML,
+ * which reads JSON too. Text around fenced blocks is left aside, as a model's reply has it. A nested
+ * mapping, as some tools write JSON, joins its keys with dots.
+ */
+export function readReturned(text: string, locale: string, source: string): { returned: Returned[] } | { problem: string } {
+  if (text.trimStart().startsWith('<')) return readXliff(text, locale, source);
+  const fenced = [...text.matchAll(/^```[^\n]*\n([\s\S]*?)^```/gm)].map((m) => m[1]);
+  const doc = parseDocument(fenced.length > 0 ? fenced.join('\n') : text);
+  if (doc.errors.length > 0 || !(isMap(doc.contents) || doc.contents === null)) {
+    const why = doc.errors[0]?.message.split('\n', 1)[0] ?? 'it is not a mapping';
+    return { problem: `the reply isn't YAML or JSON of \`key: translation\` (${why}): fix it, or ask for one YAML block` };
+  }
+  const returned: Returned[] = [];
+  const flatten = (map: YAMLMap, prefix: string) => {
+    for (const pair of map.items) {
+      const key = prefix + (isScalar(pair.key) ? String(pair.key.value) : String(pair.key));
+      if (isMap(pair.value)) flatten(pair.value, `${key}.`);
+      else returned.push({ key, value: isScalar(pair.value) ? pair.value.value : pair.value, checked: true });
+    }
+  };
+  if (isMap(doc.contents)) flatten(doc.contents, '');
+  return { returned };
+}
+
+function readXliff(text: string, locale: string, source: string): { returned: Returned[] } | { problem: string } {
+  let root: XmlElement;
+  try {
+    root = parseXml(text);
+  } catch (e) {
+    return { problem: `the file isn't XML (${messageOf(e)}): give it back as the tool exported it` };
+  }
+  if (root.name !== 'xliff') return { problem: `the file is <${root.name}>, not XLIFF: export it from the tool as XLIFF 2.0` };
+  if (!root.attrs.version?.startsWith('2.'))
+    return { problem: `the file is XLIFF ${root.attrs.version ?? 'of no version'}: export it from the tool as XLIFF 2.0` };
+  const { srcLang, trgLang } = root.attrs;
+  if (srcLang !== undefined && srcLang.toLowerCase() !== source.toLowerCase())
+    return { problem: `the file translates from ${srcLang}, and the source is ${source}: export it again from prosebook` };
+  if (trgLang === undefined)
+    return { problem: `the file names no trgLang: give it the ${locale} translations, or set trgLang="${locale}"` };
+  if (trgLang.toLowerCase() !== locale.toLowerCase())
+    return { problem: `the file translates into ${trgLang}, not ${locale}: import it as ${trgLang}` };
+
+  const returned: Returned[] = [];
+  const units = (el: XmlElement): XmlElement[] =>
+    elements(el).flatMap((child) =>
+      child.name === 'unit' ? [child] : child.name === 'file' || child.name === 'group' ? units(child) : [],
+    );
+  for (const unit of units(root)) {
+    const key = unit.attrs.id ?? '';
+    // A tool may split a unit into sentences: its text is every part's in order, what lies between them included.
+    const parts = elements(unit).filter((el) => el.name === 'segment' || el.name === 'ignorable');
+    const segments = parts.filter((el) => el.name === 'segment');
+    const sourceOf = (el: XmlElement) => elements(el).find((c) => c.name === 'source');
+    const targetOf = (el: XmlElement) => elements(el).find((c) => c.name === 'target');
+    try {
+      const unitSource = parts.map((p) => textOf(sourceOf(p))).join('');
+      const translated = segments.filter((s) => targetOf(s) !== undefined).length;
+      if (translated === 0) {
+        returned.push({ key, value: null, checked: false, source: unitSource });
+        continue;
+      }
+      if (translated < segments.length)
+        throw new Error(`${translated} of its ${segments.length} segments are translated: translate the rest`);
+      const value = parts.map((p) => textOf(targetOf(p) ?? sourceOf(p))).join('');
+      // XLIFF's default state is `initial`: nobody has looked at it yet.
+      const checked = segments.every((s) => (s.attrs.state ?? 'initial') !== 'initial');
+      returned.push({ key, value, checked, source: unitSource });
+    } catch (e) {
+      returned.push({ key, value: null, checked: false, problem: messageOf(e) });
+    }
+  }
+  return { returned };
+}
+
+/** The text of a <source> or <target>, refusing XLIFF's inline codes, which prosebook never writes. */
+function textOf(el: XmlElement | undefined): string {
+  if (el === undefined) return '';
+  return el.children
+    .map((child) => {
+      if (typeof child === 'string') return child;
+      // <cp> holds a character XML can't.
+      if (child.name === 'cp' && child.attrs.hex !== undefined) return String.fromCodePoint(Number.parseInt(child.attrs.hex, 16));
+      throw new Error(`the ${el.name} holds an inline <${child.name}>: have the tool keep placeholders as the text they were exported as`);
+    })
+    .join('');
+}
+
+const messageOf = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+const escape = (s: string) => s.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+
+interface XmlElement {
+  /** Without its namespace prefix. */
+  name: string;
+  attrs: Record<string, string>;
+  children: (XmlElement | string)[];
+}
+
+const elements = (el: XmlElement) => el.children.filter((c): c is XmlElement => typeof c !== 'string');
+
+const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+function decode(s: string, at: number): string {
+  return s.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (_, ref: string) => {
+    if (ref.startsWith('#x') || ref.startsWith('#X')) return String.fromCodePoint(Number.parseInt(ref.slice(2), 16));
+    if (ref.startsWith('#')) return String.fromCodePoint(Number.parseInt(ref.slice(1), 10));
+    const char = ENTITIES[ref];
+    if (char === undefined) throw new Error(`&${ref}; near offset ${at} is no XML entity`);
+    return char;
+  });
+}
+
+/**
+ * Just enough XML for XLIFF: elements, attributes, text, CDATA and character references. Comments,
+ * processing instructions and a doctype are skipped; no DTD is read, so no entity of one is known.
+ */
+function parseXml(text: string): XmlElement {
+  const document: XmlElement = { name: '', attrs: {}, children: [] };
+  const open: XmlElement[] = [document];
+  let i = 0;
+  const skip = (from: string, to: string) => {
+    const end = text.indexOf(to, i + from.length);
+    if (end === -1) throw new Error(`${from} at offset ${i} never ends`);
+    const body = text.slice(i + from.length, end);
+    i = end + to.length;
+    return body;
+  };
+  while (i < text.length) {
+    const lt = text.indexOf('<', i);
+    const parent = open.at(-1)!;
+    if (lt !== i) {
+      const end = lt === -1 ? text.length : lt;
+      if (open.length > 1) parent.children.push(decode(text.slice(i, end), i));
+      else if (text.slice(i, end).trim() !== '') throw new Error(`text at offset ${i} is outside the root element`);
+      i = end;
+      continue;
+    }
+    if (text.startsWith('<!--', i)) {
+      skip('<!--', '-->');
+      continue;
+    }
+    if (text.startsWith('<?', i)) {
+      skip('<?', '?>');
+      continue;
+    }
+    if (text.startsWith('<![CDATA[', i)) {
+      parent.children.push(skip('<![CDATA[', ']]>'));
+      continue;
+    }
+    if (text.startsWith('<!', i)) {
+      skip('<!', '>');
+      continue;
+    }
+    if (text.startsWith('</', i)) {
+      const at = i;
+      const name = localName(skip('</', '>').trim());
+      if (open.length === 1 || parent.name !== name) throw new Error(`</${name}> at offset ${at} closes nothing open`);
+      open.pop();
+      continue;
+    }
+    TAG.lastIndex = i;
+    const tag = TAG.exec(text);
+    if (tag === null) throw new Error(`the tag at offset ${i} is malformed`);
+    const attrs: Record<string, string> = {};
+    for (const [, name, double, single] of tag[2]!.matchAll(/([^\s=]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g))
+      attrs[localName(name!)] = decode(double ?? single ?? '', i);
+    const el: XmlElement = { name: localName(tag[1]!), attrs, children: [] };
+    if (open.length === 1 && document.children.length > 0) throw new Error(`a second root element at offset ${i}`);
+    parent.children.push(el);
+    if (tag[3] !== '/') open.push(el);
+    i += tag[0].length;
+  }
+  if (open.length > 1) throw new Error(`<${open.at(-1)!.name}> is never closed`);
+  const root = elements(document)[0];
+  if (root === undefined) throw new Error('there is no element');
+  return root;
+}
+
+const TAG = /<([^\s/>]+)((?:\s+[^\s=/>]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(\/?)>/y;
+
+const localName = (name: string) => name.slice(name.indexOf(':') + 1);

package/src/tools/extract.ts

@@ -13,7 +13,7 @@ import { basename, dirname, extname, join, relative } from 'node:path';
 import { parseSync } from 'oxc-parser';
 import { stringify } from 'yaml';
 
-import { CatalogError, KEY_PATTERN, loadCatalog } from './catalog.ts';
+import { CatalogError, KEY_PATTERN, loadCatalog, SCHEMA_LINE } from './catalog.ts';
 import type { ResolvedConfig } from './config.ts';
 import { parseMessage } from './icu.ts';
 import { singularOf } from './lint.ts';
@@ -686,7 +686,7 @@ export function applyExtract(config: ResolvedConfig, plan: ExtractPlan): string[
       return `# TODO(prosebook extract): check the key, kind and context.\n${stringify({ [e.key]: body }, { lineWidth: 0, version: '1.1' })}`;
     });
     mkdirSync(config.catalog, { recursive: true });
-    const current = existsSync(path) ? readFileSync(path, 'utf8') : '# yaml-language-server: $schema=./catalog.schema.json\n';
+    const current = existsSync(path) ? readFileSync(path, 'utf8') : `${SCHEMA_LINE}\n`;
     writeFileSync(path, `${current.replace(/\n*$/, '\n')}\n${blocks.join('\n')}`);
     written.push(path);
   }

package/src/tools/generate.ts

@@ -8,7 +8,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 
-import { loadCatalog, type Catalog, type Message } from './catalog.ts';
+import { loadCatalog, withSchemaLine, yamlFiles, type Catalog, type Message } from './catalog.ts';
 import { compileLocale, localeModule, type Entry } from './compile.ts';
 import type { ResolvedConfig } from './config.ts';
 import { readLock, reconcile, serializeLock, type Lock, type StaleTranslation } from './lock.ts';
@@ -232,6 +232,12 @@ export function render(config: ResolvedConfig, accept?: Map<string, Set<string>
 
   for (const [path, content] of nativeFiles(config, catalog, locales, entries, head)) files.set(path, content);
   files.set(join(config.catalog, 'catalog.schema.json'), `${JSON.stringify(catalogSchema(config), null, 2)}\n`);
+  // Without its schema line a catalog file has no completion, so generate adds it and --check fails there.
+  for (const file of yamlFiles(config.catalog)) {
+    const path = join(config.catalog, file);
+    const text = readFileSync(path, 'utf8');
+    if (withSchemaLine(text) !== text) files.set(path, withSchemaLine(text));
+  }
   if (Object.keys(lock.translations).length > 0 || existsSync(config.lock)) files.set(config.lock, serializeLock(lock));
   return { catalog, files, lock, stale, entries };
 }

package/src/tools/index.ts

@@ -76,7 +76,8 @@ export { toMf1 } from './mf1.ts';
 export { applyMigrate, planMigrate, type MigratePlan } from './migrate.ts';
 export { readMessage, SYNTAX_NAME, writeMessage, type MessageFormatVersion } from './syntax.ts';
 export { syntaxKind, typescriptOracle, type Span, type TypeOracle, type ValueKind } from './types.ts';
-export { todoOf, type Todo } from './todo.ts';
+export { todoMessages, todoOf, type Todo } from './todo.ts';
+export { exportOf, readReturned, type ExchangeFormat, type Exported, type Returned } from './exchange.ts';
 export { SarifReport, type SarifResult, type SarifTool } from './sarif.ts';
 export {
   hardcodedText,

package/src/tools/native/android.ts

@@ -13,10 +13,10 @@ import { join } from 'node:path';
 import type { Catalog, Message, Problem } from '#src/tools/catalog.ts';
 import type { Entry } from '#src/tools/compile.ts';
 import type { NativeTarget } from '#src/tools/config.ts';
-import { selectionOf, TYPE, type MessageFormatElement } from '#src/tools/icu.ts';
+import { TYPE, type MessageFormatElement } from '#src/tools/icu.ts';
 import { checkNames, leading, snake } from './emit.ts';
 import { fileOf, foundIn, LEAVE_OUT, wordsFor } from './model.ts';
-import { formatString, noteOf, type Printf } from './printf.ts';
+import { checkPlural, formatString, noteOf, type PluralHolder, type Printf } from './printf.ts';
 
 const KEYWORDS = new Set(
   'abstract assert boolean break byte case catch char class const continue default do double else enum extends false final finally float for goto if implements import instanceof int interface long native new null package private protected public return short static strictfp super switch synchronized this throw throws transient true try void volatile while'.split(
@@ -79,11 +79,18 @@ const PRINTF: Printf = {
   formatter: 'String.format',
   holder: 'Android resources',
   string: 's',
+  count: 'd',
   escape,
   plural: (name) =>
     `{${name}} is a second plural in the message, and Android's <plurals> picks on one count: split it into a key per count, ${LEAVE_OUT}`,
 };
 
+const PLURALS: PluralHolder = {
+  platform: 'Android',
+  plurals: "Android's <plurals>",
+  exact: ' (its zero is a category, which most languages never pick)',
+};
+
 /**
  * A message as `<string>`, or `<plurals>` when it holds a plural. Android's picks between whole
  * messages, so the text around the plural goes into each arm: the pseudo-locale's brackets, or a
@@ -99,29 +106,7 @@ function resource(name: string, ast: MessageFormatElement[], args: string[]): st
     return `    <string name="${name}"${raw}>${value(written)}</string>`;
   }
   const [before, after] = [ast.slice(0, at), ast.slice(at + 1)];
-  const named = `{${plural.value}}`;
-  if (plural.pluralType === 'ordinal') {
-    throw new Error(
-      `${named} is an ordinal, and Android's <plurals> are cardinal only: write a key per case and pick one in code, ${LEAVE_OUT}`,
-    );
-  }
-  if (plural.offset !== 0) {
-    throw new Error(
-      `${named} has an offset, which Android's <plurals> don't: count without it, and say the rest in each arm, ${LEAVE_OUT}`,
-    );
-  }
-  const selection = selectionOf(plural);
-  if (selection !== undefined && (selection.fn.name !== 'integer' || Object.keys(selection.fn.options).length > 0)) {
-    throw new Error(
-      `${named} selects with :${selection.fn.name} and its options, and Android selects on the count as an integer: select with a bare :number or :integer, ${LEAVE_OUT}`,
-    );
-  }
-  const exact = Object.keys(plural.options).filter((k) => k.startsWith('='));
-  if (exact.length > 0) {
-    throw new Error(
-      `${named} has the arm ${exact.join(', ')}, and Android's <plurals> have none for one number (its zero is a category, which most languages never pick): say it in a category's arm, or write a key for it and pick that in code, ${LEAVE_OUT}`,
-    );
-  }
+  checkPlural(plural, PLURALS);
   const items = Object.entries(plural.options).map(
     ([category, option]) =>
       `        <item quantity="${category}">${value(formatString([...before, ...option.value, ...after], args, PRINTF, plural.value))}</item>`,

package/src/tools/native/apple.ts

@@ -13,10 +13,10 @@ import { join, relative } from 'node:path';
 import type { Catalog, Message, Problem } from '#src/tools/catalog.ts';
 import type { Entry } from '#src/tools/compile.ts';
 import type { NativeTarget } from '#src/tools/config.ts';
-import { staticLiteral } from '#src/tools/icu.ts';
+import { staticLiteral, TYPE, type MessageFormatElement } from '#src/tools/icu.ts';
 import { checkNames } from './emit.ts';
 import { fileOf, foundIn, LEAVE_OUT, restOf, wordsFor } from './model.ts';
-import { formatString, noteOf, type Printf } from './printf.ts';
+import { checkPlural, formatString, noteOf, type PluralHolder, type Printf } from './printf.ts';
 
 /** Text inside a `.strings` file's quotes; `%` doubled where the string has arguments. */
 function escape(text: string, formatted: boolean): string {
@@ -29,11 +29,54 @@ const PRINTF: Printf = {
   formatter: 'String(format:)',
   holder: '.strings files',
   string: '@',
+  count: 'lld',
   escape,
+  // A plural at the top goes to the .stringsdict; one under a select never gets here, as the select fails first.
+  plural: (name) => `{${name}} is a plural inside another, which a .strings file can't hold: say it without, ${LEAVE_OUT}`,
+};
+
+const xml = (text: string) => text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+
+const DICT: Printf = {
+  ...PRINTF,
+  holder: '.stringsdict files',
+  escape: (text, formatted) => (formatted ? xml(text).replaceAll('%', '%%') : xml(text)),
   plural: (name) =>
-    `{${name}} is a plural, which a .strings file can't hold (it takes a .stringsdict, which this target doesn't write): show it from the Swift target, ${LEAVE_OUT}`,
+    `{${name}} is a plural inside another plural's arm, which a .stringsdict here can't hold: write a key per case and pick one in code, ${LEAVE_OUT}`,
 };
 
+const PLURALS: PluralHolder = { platform: 'Apple', plurals: "a .stringsdict's plurals", exact: '' };
+
+/**
+ * A message holding plurals as a `.stringsdict` entry: its format, with each plural a variable
+ * (`%1$#@count@`) whose arms the system picks by the count's category, from its own CLDR rules.
+ */
+function dictEntry(name: string, ast: MessageFormatElement[], args: string[]): string {
+  const variables: string[] = [];
+  const taken = new Map<string, number>();
+  let format = '';
+  for (const el of ast) {
+    if (el.type !== TYPE.plural) {
+      format += formatString([el], args, DICT);
+      continue;
+    }
+    checkPlural(el, PLURALS);
+    const base = el.value.replace(/\W/g, '_');
+    const seen = (taken.get(base) ?? 0) + 1;
+    taken.set(base, seen);
+    const variable = seen === 1 ? base : `${base}${seen}`;
+    format += `%${args.indexOf(el.value) + 1}$#@${variable}@`;
+    const arms = Object.entries(el.options).map(
+      ([category, option]) =>
+        `            <key>${category}</key>\n            <string>${formatString(option.value, args, DICT, el.value)}</string>\n`,
+    );
+    variables.push(
+      `        <key>${variable}</key>\n        <dict>\n            <key>NSStringFormatSpecTypeKey</key>\n            <string>NSStringPluralRuleType</string>\n            <key>NSStringFormatValueTypeKey</key>\n            <string>${DICT.count}</string>\n${arms.join('')}        </dict>\n`,
+    );
+  }
+  return `    <key>${xml(name)}</key>\n    <dict>\n        <key>NSStringLocalizedFormatKey</key>\n        <string>${format}</string>\n${variables.join('')}    </dict>\n`;
+}
+
 const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
 
 /** An XML plist's string values by key, read as its text is: every `<key>` followed by a `<string>`. */
@@ -107,33 +150,52 @@ export function appleStrings(
   }
 
   const lines = new Map<string, string[]>(locales.map((l) => [l, []]));
+  const dicts = new Map<string, string[]>(locales.map((l) => [l, []]));
   const failed = new Set(problems.map((p) => p.key));
   for (const { m, name } of taken) {
     if (failed.has(m.key)) continue;
     const args = [...m.args.keys()];
     const note = noteOf(m);
     const head = note === '' ? '' : `/* ${note.replaceAll('*/', '* /')} */\n`;
-    const written = new Map<string, string>();
+    const comment = note === '' ? '' : `    <!-- ${note.replace(/-{2,}/g, '-')} -->\n`;
+    const written = new Map<string, { dict: boolean; entry: string }>();
     for (const locale of locales) {
       const found = foundIn(m.key, locale, locales, asts);
       if (found === undefined) continue;
       let entry = written.get(found);
       if (entry === undefined) {
+        const ast = asts.get(found)!.get(m.key)!;
+        const dict = ast.some((el) => el.type === TYPE.plural);
         try {
-          entry = `${head}"${escape(name, false)}" = "${formatString(asts.get(found)!.get(m.key)!, args, PRINTF)}";\n`;
+          entry = dict
+            ? { dict, entry: `${comment}${dictEntry(name, ast, args)}` }
+            : { dict, entry: `${head}"${escape(name, false)}" = "${formatString(ast, args, PRINTF)}";\n` };
         } catch (e) {
           error(m, (e as Error).message, fileOf(m, found, source));
           break;
         }
         written.set(found, entry);
       }
-      lines.get(locale)!.push(entry);
+      (entry.dict ? dicts : lines).get(locale)!.push(entry.entry);
     }
   }
 
-  const top = `/* ${banner.replace(/^\/\/ /, '')} */\n`;
+  const said = banner.replace(/^\/\/ /, '');
   const files = new Map(
-    locales.map((locale) => [join(target.out, `${locale}.lproj`, `${target.name}.strings`), [top, ...lines.get(locale)!].join('\n')]),
+    locales.map((locale) => [
+      join(target.out, `${locale}.lproj`, `${target.name}.strings`),
+      [`/* ${said} */\n`, ...lines.get(locale)!].join('\n'),
+    ]),
   );
+  // The system looks a key up in the .stringsdict of the table's name first, so a plural lands there.
+  if ([...dicts.values()].some((d) => d.length > 0)) {
+    for (const locale of locales) {
+      const body = dicts.get(locale)!.join('');
+      files.set(
+        join(target.out, `${locale}.lproj`, `${target.name}.stringsdict`),
+        `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<!-- ${said.replace(/-{2,}/g, '-')} -->\n<plist version="1.0">\n<dict>\n${body}</dict>\n</plist>\n`,
+      );
+    }
+  }
   return { files, problems };
 }