@likolabs/i18nmd 0.1.1

package/lib/llm.mjs

@@ -0,0 +1,138 @@
+// Translate language files with an Anthropic Messages API or an
+// OpenAI-compatible /chat/completions endpoint. Plain fetch keeps the tool
+// dependency-free and works with any compatible base URL (proxies, gateways,
+// local servers).
+import { parseCatalog, serializeCatalog, validateCatalog, textOf } from './catalog.mjs';
+
+const ANTHROPIC = 'https://api.anthropic.com';
+const DEFAULT_ANTHROPIC_MODEL = 'claude-opus-5-5';
+
+/**
+ * Settings come from flags, then I18NMD_* variables, then the provider's own
+ * variables. The key is never printed.
+ */
+export function llmConfig(options = {}, env = process.env) {
+  let baseUrl = options['base-url'] || env.I18NMD_BASE_URL;
+  let apiKey = env.I18NMD_API_KEY;
+  let provider = options.provider || env.I18NMD_PROVIDER;
+  if (!apiKey && !baseUrl && env.ANTHROPIC_API_KEY) { apiKey = env.ANTHROPIC_API_KEY; baseUrl = env.ANTHROPIC_BASE_URL || ANTHROPIC; provider ||= 'anthropic'; }
+  if (!apiKey && !baseUrl && env.OPENAI_API_KEY) { apiKey = env.OPENAI_API_KEY; baseUrl = env.OPENAI_BASE_URL || 'https://api.openai.com/v1'; provider ||= 'openai'; }
+  apiKey ||= env.ANTHROPIC_API_KEY || env.OPENAI_API_KEY;
+  if (!baseUrl && !apiKey) throw new Error('Set I18NMD_API_KEY (and I18NMD_BASE_URL for a non-Anthropic endpoint), or ANTHROPIC_API_KEY / OPENAI_API_KEY.');
+  baseUrl = (baseUrl || ANTHROPIC).replace(/\/+$/, '');
+  provider ||= /anthropic\.com|\/v1\/messages$/.test(baseUrl) || apiKey?.startsWith('sk-ant-') ? 'anthropic' : 'openai';
+  if (!['anthropic', 'openai'].includes(provider)) throw new Error('--provider must be anthropic or openai.');
+  const model = options.model || env.I18NMD_MODEL || (provider === 'anthropic' ? DEFAULT_ANTHROPIC_MODEL : undefined);
+  if (!model) throw new Error('Choose a model with --model or I18NMD_MODEL for an OpenAI-compatible endpoint.');
+  return { baseUrl, apiKey, provider, model };
+}
+
+function endpoint({ baseUrl, provider }) {
+  if (provider === 'anthropic') return /\/messages$/.test(baseUrl) ? baseUrl : /\/v1$/.test(baseUrl) ? `${baseUrl}/messages` : `${baseUrl}/v1/messages`;
+  return /\/chat\/completions$/.test(baseUrl) ? baseUrl : `${baseUrl}/chat/completions`;
+}
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/** One system + user exchange; returns the reply text. */
+export async function chat(config, system, user, { fetchImpl = fetch, retries = 4 } = {}) {
+  const anthropic = config.provider === 'anthropic';
+  const official = anthropic && config.baseUrl.startsWith(ANTHROPIC);
+  const headers = { 'content-type': 'application/json' };
+  let body;
+  if (anthropic) {
+    if (config.apiKey) headers['x-api-key'] = config.apiKey;
+    headers['anthropic-version'] = '2023-06-01';
+    body = { model: config.model, max_tokens: 16000, system, messages: [{ role: 'user', content: user }] };
+    // On Anthropic's API, let a declined request continue on a fallback model.
+    if (official) { headers['anthropic-beta'] = 'server-side-fallback-2026-07-01'; body.fallbacks = 'default'; }
+  } else {
+    if (config.apiKey) headers.authorization = `Bearer ${config.apiKey}`;
+    body = { model: config.model, messages: [{ role: 'system', content: system }, { role: 'user', content: user }] };
+  }
+  for (let attempt = 0; ; attempt++) {
+    let response;
+    try { response = await fetchImpl(endpoint(config), { method: 'POST', headers, body: JSON.stringify(body) }); }
+    catch (error) { if (attempt < retries) { await sleep(1000 * 2 ** attempt); continue; } throw new Error(`Could not reach ${endpoint(config)}: ${error.message}`); }
+    if (response.status === 429 || response.status >= 500) {
+      if (attempt < retries) { await sleep(Number(response.headers.get('retry-after')) * 1000 || 1000 * 2 ** attempt); continue; }
+    }
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) throw new Error(`${config.provider} API ${response.status}: ${data.error?.message || response.statusText}`);
+    if (anthropic) {
+      if (data.stop_reason === 'refusal') throw new Error('The model declined to translate this batch.');
+      if (data.stop_reason === 'max_tokens') throw new Error('The reply was cut off; use a smaller --batch.');
+      return (data.content || []).filter(block => block.type === 'text').map(block => block.text).join('');
+    }
+    const choice = data.choices?.[0];
+    if (choice?.finish_reason === 'length') throw new Error('The reply was cut off; use a smaller --batch.');
+    return choice?.message?.content ?? '';
+  }
+}
+
+function systemPrompt(catalog, target) {
+  const source = catalog.languages[catalog.source];
+  return [
+    `You localize software interface strings from ${source} (${catalog.source}) into ${target.english || target.name} (${target.code}).`,
+    target.custom ? `"${target.english}" is not a standard language. Write in that style or variety consistently, keeping the text understandable.` : 'Write natural, idiomatic text a native speaker would expect in a polished product, using the conventional register for software in that language.',
+    'Each message is ICU MessageFormat. Keep placeholder names such as {name}, tag names such as <b>…</b>, and the plural/select/selectordinal keywords and select branch names exactly as they are; translate only the human text, including the text inside branches and tags. For plurals, provide the CLDR plural categories the target language needs and always keep "other". Keep # inside plural branches. Write a literal apostrophe as \'\' only when it sits next to { or }. Preserve leading and trailing spaces.',
+    'Use the Context line to choose the right meaning and length. Interface text should be concise. Keep terminology consistent with the existing translations you are given.',
+    'Reply with Markdown only, in exactly the input format: for each token, a "## token" heading followed by an ```icu fenced block. Include every token you were given, in the same order, and nothing else.',
+  ].join('\n\n');
+}
+
+function userPrompt(catalog, target, messages, previous, glossary) {
+  let text = '';
+  if (glossary.length) text += `Existing ${target.name} translations, for consistent terminology:\n\n${glossary.map(([s, t]) => `- ${JSON.stringify(s)} → ${JSON.stringify(t)}`).join('\n')}\n\n`;
+  const subset = { ...catalog, messages: messages.map(m => ({ ...m, translations: { [catalog.source]: m.translations[catalog.source] }, invalid: undefined })) };
+  text += `Translate these ${messages.length} messages:\n\n${serializeCatalog(subset, { locale: catalog.source }).replace(/^# .*\n\n/, '')}`;
+  const outdated = messages.filter(m => previous[m.key]);
+  if (outdated.length) text += `\nThese tokens had an earlier translation for older source text; reuse its wording where it still fits:\n\n${outdated.map(m => `- ${m.key}: ${JSON.stringify(previous[m.key])}`).join('\n')}\n`;
+  return text;
+}
+
+/** Parse a reply and check each message against its source; returns { ok, errors }. */
+export function readReply(reply, catalog, target, messages) {
+  const body = reply.trim().replace(/^````?(?:md|markdown)?\n([\s\S]*?)\n````?$/, '$1');
+  const ok = Object.create(null), errors = Object.create(null);
+  let parsed;
+  try { parsed = parseCatalog(`# ${target.name}\n\n${body}\n`, { locale: target.code, allowIncomplete: true }); }
+  catch (error) { for (const m of messages) errors[m.key] = `unreadable reply: ${error.message}`; return { ok, errors }; }
+  const replies = new Map(parsed.messages.map(m => [m.key, m.translations[target.code]]));
+  for (const message of messages) {
+    const text = replies.get(message.key);
+    if (text === undefined) { errors[message.key] = 'missing from the reply'; continue; }
+    try {
+      validateCatalog({ source: catalog.source, syntax: catalog.syntax, languages: { [catalog.source]: 'source', [target.code]: 'target' }, messages: [{ key: message.key, optional: message.optional, translations: { [catalog.source]: message.translations[catalog.source], [target.code]: text } }] });
+      ok[message.key] = text;
+    } catch (error) { errors[message.key] = error.message; }
+  }
+  return { ok, errors };
+}
+
+/**
+ * Translate the given tokens into one language, in batches, retrying invalid
+ * messages once with the validation error. Calls onBatch(results) after each
+ * batch so callers can save progress. Returns the keys that still failed.
+ */
+export async function translateLanguage(catalog, target, keys, config, { batchSize = 40, onBatch = () => {}, chatImpl = chat } = {}) {
+  const messages = catalog.messages.filter(m => keys.includes(m.key));
+  const previous = Object.fromEntries(messages.map(m => [m.key, textOf(m, target.code)]).filter(([, t]) => t !== undefined));
+  const glossary = catalog.messages.filter(m => !keys.includes(m.key) && Object.hasOwn(m.translations, target.code) && m.translations[catalog.source].length < 60).slice(0, 40).map(m => [m.translations[catalog.source], m.translations[target.code]]);
+  const failed = Object.create(null);
+  for (let i = 0; i < messages.length; i += batchSize) {
+    const batch = messages.slice(i, i + batchSize);
+    const system = systemPrompt(catalog, target);
+    let { ok, errors } = readReply(await chatImpl(config, system, userPrompt(catalog, target, batch, previous, glossary)), catalog, target, batch);
+    const retry = batch.filter(m => errors[m.key]);
+    if (retry.length) {
+      const feedback = `\n\nA previous attempt had these problems; fix them:\n${retry.map(m => `- ${m.key}: ${errors[m.key]}`).join('\n')}`;
+      const second = readReply(await chatImpl(config, system, userPrompt(catalog, target, retry, previous, glossary) + feedback), catalog, target, retry);
+      Object.assign(ok, second.ok);
+      errors = second.errors;
+    }
+    Object.assign(failed, errors);
+    await onBatch(ok);
+  }
+  return failed;
+}

package/lib/lock.mjs

@@ -0,0 +1,111 @@
+// i18nmd.lock.json keeps bookkeeping out of the Markdown. For every translation
+// it records a fingerprint of the source text it was written against and of the
+// translation itself. A translation is stale when its source text changed and
+// the translation has not been edited since; editing it accepts it.
+import { readFile, access } from 'node:fs/promises';
+import path from 'node:path';
+import { hashMessage, textOf } from './catalog.mjs';
+
+export const LOCK_FILE = 'i18nmd.lock.json';
+
+export function lockPathFor(input, isDirectory) {
+  return isDirectory ? path.join(input, LOCK_FILE) : input.replace(/\.md$/, '') + '.lock.json';
+}
+
+/** The nearest enclosing directory named translations, i18n or locales, if any. */
+export function namedRoot(dir) {
+  const parts = path.resolve(dir).split(path.sep);
+  const index = parts.findLastIndex(part => ['translations', 'i18n', 'locales'].includes(part));
+  return index < 0 ? undefined : parts.slice(0, index + 1).join(path.sep) || path.sep;
+}
+
+/**
+ * The lock for a directory: its own, or one in an enclosing directory when the
+ * directory is a division of a larger tree. The search stops at the working
+ * directory or a translations/, i18n/ or locales/ directory; a new lock goes in
+ * the latter, so every division shares one.
+ */
+export async function findLock(dir) {
+  const start = path.resolve(dir), named = namedRoot(dir), cwd = path.resolve('.');
+  const stops = [named, start.startsWith(cwd + path.sep) ? cwd : undefined].filter(Boolean);
+  for (let current = start; ; current = path.dirname(current)) {
+    const file = path.join(current, LOCK_FILE);
+    try { await access(file); return { file: path.relative('.', file) || LOCK_FILE, partial: current !== start }; } catch { /* keep looking */ }
+    if (stops.includes(current) || current === path.dirname(current) || !stops.length) break;
+  }
+  const home = named || start;
+  return { file: path.relative('.', path.join(home, LOCK_FILE)), partial: home !== start };
+}
+
+export async function readLock(file) {
+  try {
+    const lock = JSON.parse(await readFile(file, 'utf8'));
+    return { source: lock.source, translations: lock.translations || {} };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { source: undefined, translations: {} };
+    throw new Error(`${file}: ${error.message}`);
+  }
+}
+
+export function serializeLock(lock) {
+  const sorted = Object.fromEntries(Object.keys(lock.translations).sort().map(locale => [locale, Object.fromEntries(Object.entries(lock.translations[locale]).sort(([a], [b]) => a.localeCompare(b)))]));
+  return JSON.stringify({ source: lock.source, translations: sorted }, null, 2) + '\n';
+}
+
+const fingerprint = (message, catalog, locale) => `${hashMessage(message.translations[catalog.source])}:${hashMessage(textOf(message, locale))}`;
+
+function stale(message, catalog, locale, entry) {
+  if (!Object.hasOwn(message.translations, locale) && message.invalid?.[locale] !== undefined) return true;
+  if (!entry) return false;
+  const [source, translation] = entry.split(':');
+  return source !== hashMessage(message.translations[catalog.source]) && translation === hashMessage(textOf(message, locale));
+}
+
+/** Per-language progress: tokens missing, stale, and done. */
+export function report(catalog, lock) {
+  return Object.keys(catalog.languages).filter(l => l !== catalog.source).map(locale => {
+    const row = { locale, name: catalog.languages[locale], total: catalog.messages.length, missing: [], stale: [] };
+    for (const message of catalog.messages) {
+      if (textOf(message, locale) === undefined) row.missing.push(message.key);
+      else if (stale(message, catalog, locale, lock.translations[locale]?.[message.key])) row.stale.push(message.key);
+    }
+    row.done = row.total - row.missing.length - row.stale.length;
+    return row;
+  });
+}
+
+/**
+ * Bring the lock up to date with the files; returns human-readable changes.
+ * partial: the catalog is one division of a larger tree, so entries for other
+ * tokens and languages are kept.
+ */
+export function syncLock(catalog, lock, { partial = false } = {}) {
+  const changes = [];
+  const keys = new Set(catalog.messages.map(message => message.key));
+  const next = partial ? { ...lock.translations } : {};
+  for (const locale of Object.keys(catalog.languages)) {
+    if (locale === catalog.source) continue;
+    const previous = lock.translations[locale] || {};
+    const entries = next[locale] = partial ? Object.fromEntries(Object.entries(previous).filter(([key]) => !keys.has(key))) : {};
+    for (const message of catalog.messages) {
+      if (textOf(message, locale) === undefined) continue;
+      const entry = previous[message.key];
+      if (stale(message, catalog, locale, entry)) {
+        entries[message.key] = entry || fingerprint(message, catalog, locale);
+        if (!message.invalid?.[locale]) changes.push(`${locale}: ${message.key} is stale; its source text changed`);
+        continue;
+      }
+      const current = fingerprint(message, catalog, locale);
+      if (entry && entry.split(':')[0] !== current.split(':')[0]) changes.push(`${locale}: ${message.key} accepted; the translation was updated after its source changed`);
+      entries[message.key] = current;
+    }
+  }
+  lock.source = catalog.source;
+  lock.translations = next;
+  return changes;
+}
+
+/** Record that a translation now matches the current source text. */
+export function markCurrent(catalog, lock, locale, message) {
+  (lock.translations[locale] ||= {})[message.key] = fingerprint(message, catalog, locale);
+}

package/lib/messages.mjs

@@ -0,0 +1,130 @@
+// The compiler parses a documented ICU subset. No parsing happens in the app.
+export function parseMessage(text, syntax = 'icu') {
+  if (typeof text !== 'string') throw new Error('Messages must be strings.');
+  if (syntax === 'python') {
+    const nodes = [];
+    let literal = '';
+    const flush = () => { if (literal) nodes.push(literal); literal = ''; };
+    for (let i = 0; i < text.length;) {
+      if (text.slice(i, i + 2) === '{{' || text.slice(i, i + 2) === '}}') {
+        literal += text[i]; i += 2;
+      } else if (text[i] === '{') {
+        const end = text.indexOf('}', i);
+        const name = text.slice(i + 1, end);
+        if (end < 0 || !/^[a-zA-Z_][\w]*$/.test(name)) throw new Error('Python messages support named {placeholders} only.');
+        flush(); nodes.push({ type: 'argument', name }); i = end + 1;
+      } else if (text[i] === '}') throw new Error('Unmatched closing brace.');
+      else literal += text[i++];
+    }
+    flush(); return nodes;
+  }
+  if (syntax !== 'icu') throw new Error(`Unknown message syntax: ${syntax}`);
+  let pos = 0;
+  const fail = message => { throw new Error(`${message} (character ${pos + 1})`); };
+  const space = () => { while (/\s/.test(text[pos] || '') && pos < text.length) pos++; };
+  const word = () => { const start = pos; while (/[\w.-]/.test(text[pos] || '') && pos < text.length) pos++; return text.slice(start, pos); };
+  const expect = char => { space(); if (text[pos++] !== char) fail(`Expected ${char}`); };
+  function sequence(nested = false, plural = false, depth = 0, closing) {
+    if (depth > 40) fail('Message nesting is too deep');
+    const nodes = [];
+    let literal = '';
+    const flush = () => { if (literal) nodes.push(literal); literal = ''; };
+    while (pos < text.length) {
+      const c = text[pos];
+      if (c === '}') { if (!nested) fail('Unmatched closing brace'); break; }
+      // Rich-text tags: <b>chunks</b>. A closing tag ends the enclosing sequence.
+      if (c === '<' && syntax === 'icu') {
+        const close = /^<\/([a-zA-Z][\w-]*)>/.exec(text.slice(pos));
+        if (close) { if (closing !== close[1]) fail(`Unexpected </${close[1]}>`); break; }
+        const open = /^<([a-zA-Z][\w-]*)>/.exec(text.slice(pos));
+        if (open) {
+          if (open[1] === '__proto__') fail('Invalid tag name');
+          flush(); pos += open[0].length;
+          const children = sequence(nested, plural, depth + 1, open[1]);
+          if (text.slice(pos, pos + open[1].length + 3) !== `</${open[1]}>`) fail(`Unclosed <${open[1]}>`);
+          pos += open[1].length + 3;
+          nodes.push({ type: 'tag', name: open[1], children });
+          continue;
+        }
+      }
+      if (c === "'") {
+        if (text[pos + 1] === "'") { literal += "'"; pos += 2; continue; }
+        if (['{', '}', '<', ...(plural ? ['#'] : [])].includes(text[pos + 1])) {
+          pos++;
+          while (pos < text.length) {
+            if (text[pos] === "'") {
+              if (text[pos + 1] === "'") { literal += "'"; pos += 2; }
+              else { pos++; break; }
+            } else literal += text[pos++];
+          }
+          continue;
+        }
+      }
+      if (c === '#' && plural) { flush(); nodes.push({ type: 'pound' }); pos++; continue; }
+      if (c !== '{') { literal += c; pos++; continue; }
+      flush(); pos++; space();
+      const name = word();
+      if (!/^[a-zA-Z_]\w*$/.test(name) || name === '__proto__') fail('Expected a named placeholder');
+      space();
+      if (text[pos] === '}') { pos++; nodes.push({ type: 'argument', name }); continue; }
+      expect(','); space(); const type = word(); space();
+      if (['plural', 'selectordinal', 'select'].includes(type)) {
+        expect(','); space();
+        let offset = 0;
+        if (type !== 'select' && text.slice(pos, pos + 7) === 'offset:') {
+          pos += 7; space(); const n = /^\d+/.exec(text.slice(pos));
+          if (!n) fail('Expected a nonnegative plural offset');
+          offset = Number(n[0]); pos += n[0].length; space();
+        }
+        const options = Object.create(null);
+        while (pos < text.length && text[pos] !== '}') {
+          let selector;
+          if (text[pos] === '=' && type !== 'select') {
+            pos++; const n = /^-?\d+(?:\.\d+)?/.exec(text.slice(pos));
+            if (!n) fail('Expected a numeric plural selector');
+            selector = '=' + Number(n[0]); pos += n[0].length;
+          } else selector = word();
+          if (!selector || selector === '__proto__') fail('Expected a branch name');
+          if (type !== 'select' && !selector.startsWith('=') && !['zero', 'one', 'two', 'few', 'many', 'other'].includes(selector)) fail(`Unknown plural category ${selector}`);
+          if (Object.hasOwn(options, selector)) fail(`Duplicate branch ${selector}`);
+          expect('{'); options[selector] = sequence(true, type !== 'select' || plural, depth + 1); expect('}'); space();
+        }
+        if (!Object.hasOwn(options, 'other')) fail(`${type} needs an other branch`);
+        expect('}'); nodes.push({ type, name, offset, options });
+      } else if (['number', 'date', 'time'].includes(type)) {
+        let style = '';
+        if (text[pos] === ',') {
+          pos++; const start = pos; while (pos < text.length && text[pos] !== '}') pos++;
+          style = text.slice(start, pos).trim();
+        }
+        if (type === 'number' && !['', 'integer', 'percent'].includes(style) && !/^::currency\/[A-Z]{3}$/.test(style)) fail(`Unsupported number style ${style}`);
+        if (type !== 'number' && !['', 'short', 'medium', 'long', 'full'].includes(style)) fail(`Unsupported ${type} style ${style}`);
+        expect('}'); nodes.push({ type, name, style });
+      } else fail(`Unsupported message type ${type}`);
+    }
+    flush(); return nodes;
+  }
+  return sequence();
+}
+
+export function argumentsFor(nodes, out = Object.create(null)) {
+  for (const n of nodes) {
+    if (typeof n === 'string' || n.type === 'pound') continue;
+    if (n.type === 'tag') {
+      if (out[n.name] && out[n.name] !== 'tag') throw new Error(`<${n.name}> is also used as a placeholder.`);
+      out[n.name] = 'tag'; argumentsFor(n.children, out); continue;
+    }
+    if (out[n.name] === 'tag') throw new Error(`{${n.name}} is also used as a tag.`);
+    const type = ['number', 'plural', 'selectordinal'].includes(n.type) ? 'number' : ['date', 'time'].includes(n.type) ? 'date' : n.type === 'select' ? 'select' : 'string';
+    if (out[n.name] && out[n.name] !== type && out[n.name] !== 'string' && type !== 'string') throw new Error(`Conflicting types for {${n.name}}.`);
+    if (!out[n.name] || type !== 'string') out[n.name] = type;
+    if (n.options) for (const branch of Object.values(n.options)) argumentsFor(branch, out);
+  }
+  return out;
+}
+
+// A lone apostrophe is literal (ICU 4.8+), so "isn't" stays readable; only one
+// that would start a quote, before a quoted character or another apostrophe, is doubled.
+export function escapeMessageLiteral(text) {
+  return text.replace(/'(?=['{}#<|])|[{}]|<(?=\/?[a-zA-Z])/g, match => match === "'" ? "''" : `'${match}'`);
+}

package/lib/runtime.mjs

@@ -0,0 +1,162 @@
+/**
+ * Format a compiled catalog using the host's Intl implementation.
+ * Messages without tags return strings. Messages with rich-text tags call the
+ * matching function with the tag's rendered chunks and return an array, which
+ * frameworks such as React render directly.
+ * onError receives problems such as an unknown token or a missing value. By
+ * default they are logged and the message degrades instead of crashing the UI;
+ * pass `error => { throw error; }` to fail fast in tests.
+ */
+export function createI18n(catalog, { onError = error => console.error(`i18nmd: ${error.message}`) } = {}) {
+  function value(values, name) {
+    if (!Object.hasOwn(values, name)) { onError(new Error(`Missing value for {${name}}.`)); return undefined; }
+    return values[name];
+  }
+  function render(nodes, locale, values, pound) {
+    const parts = [];
+    const push = part => { if (typeof part === 'string' && typeof parts.at(-1) === 'string') parts[parts.length - 1] += part; else if (part !== '') parts.push(part); };
+    const pushAll = rendered => Array.isArray(rendered) ? rendered.forEach(push) : push(rendered);
+    for (const n of nodes) {
+      if (typeof n === 'string') { push(n); continue; }
+      if (n.type === 'pound') { push(new Intl.NumberFormat(locale).format(pound)); continue; }
+      if (n.type === 'tag') {
+        const children = render(n.children, locale, values, pound);
+        const fn = value(values, n.name);
+        if (typeof fn !== 'function') { if (fn !== undefined) onError(new Error(`<${n.name}> needs a function.`)); pushAll(children); continue; }
+        push(fn(Array.isArray(children) ? children : [children]));
+        continue;
+      }
+      if (!Object.hasOwn(values, n.name)) { value(values, n.name); push(`{${n.name}}`); continue; }
+      const v = values[n.name];
+      // Like JSX, a plain placeholder renders null or undefined as nothing.
+      if (n.type === 'argument') { push(v == null ? '' : String(v)); continue; }
+      if (v == null) { onError(new Error(`Missing value for {${n.name}}.`)); push(`{${n.name}}`); continue; }
+      if (['number', 'plural', 'selectordinal'].includes(n.type) && (typeof v !== 'number' || !Number.isFinite(v))) { onError(new Error(`{${n.name}} must be a finite number.`)); push(String(v)); continue; }
+      if (n.type === 'number') {
+        const options = n.style === 'integer' ? { maximumFractionDigits: 0 } : n.style === 'percent' ? { style: 'percent' } : n.style.startsWith('::currency/') ? { style: 'currency', currency: n.style.slice(11) } : {};
+        push(new Intl.NumberFormat(locale, options).format(v)); continue;
+      }
+      if (n.type === 'date' || n.type === 'time') {
+        const date = v instanceof Date ? v : typeof v === 'number' ? new Date(v) : null;
+        if (!date || Number.isNaN(date.getTime())) { onError(new Error(`{${n.name}} must be a Date or a timestamp.`)); push(String(v)); continue; }
+        push(new Intl.DateTimeFormat(locale, { [n.type + 'Style']: n.style || 'medium' }).format(date)); continue;
+      }
+      if (n.type === 'select') { pushAll(render(Object.hasOwn(n.options, String(v)) ? n.options[String(v)] : n.options.other, locale, values, pound)); continue; }
+      const adjusted = v - n.offset;
+      const category = new Intl.PluralRules(locale, { type: n.type === 'selectordinal' ? 'ordinal' : 'cardinal' }).select(adjusted);
+      pushAll(render(n.options['=' + v] || n.options[category] || n.options.other, locale, values, adjusted));
+    }
+    return parts.length === 0 ? '' : parts.length === 1 && typeof parts[0] === 'string' ? parts[0] : parts;
+  }
+  return function i18nmd(token, language = catalog.source, values = {}) {
+    if (!Object.hasOwn(catalog.messages, token)) { onError(new Error(`Unknown translation token: ${token}`)); return token; }
+    let requested = language;
+    try { requested = Intl.getCanonicalLocales(language)[0]; } catch { /* Custom language names use source formatting. */ }
+    const entry = catalog.messages[token];
+    const base = requested.split('-')[0];
+    const languageUsed = Object.hasOwn(entry, requested) ? requested : Object.hasOwn(entry, base) ? base : catalog.source;
+    // Fallback content is formatted with its actual language's plural rules.
+    let formattingLocale = languageUsed;
+    try { Intl.getCanonicalLocales(formattingLocale); } catch { formattingLocale = catalog.source; }
+    try { Intl.getCanonicalLocales(formattingLocale); } catch { formattingLocale = 'en'; }
+    return render(entry[languageUsed], formattingLocale, values || {});
+  };
+}
+
+/** The catalog language that best matches a requested one: exact, then base language. */
+export function matchLanguage(catalog, requested) {
+  if (!requested) return undefined;
+  let canonical = requested;
+  try { canonical = Intl.getCanonicalLocales(requested)[0]; } catch { /* custom identifiers */ }
+  if (Object.hasOwn(catalog.languages, canonical)) return canonical;
+  const base = canonical.split('-')[0];
+  return Object.keys(catalog.languages).find(l => l === base || l.split('-')[0] === base);
+}
+
+/**
+ * The current language and the messages loaded so far, shared by everything that
+ * translates. Source-language messages arrive with each division's module
+ * (store.add); another language arrives whole from load(language) before
+ * setLanguage switches to it, so a page never mixes languages mid-render.
+ * The language starts as the reader's remembered choice, then the browser's best
+ * match, then the source; in a browser the choice is remembered under
+ * options.storageKey ("i18nmd:language"; null to not remember). divisions lists
+ * the division names, for clearer errors.
+ */
+export function createLanguage(languages, source, { load, divisions = [], storageKey = 'i18nmd:language', onError = e => console.error(`i18nmd: ${e.message}`) } = {}) {
+  const store = { source, languages, messages: Object.create(null), divisions, loaded: new Set([source]) };
+  store.add = (table, language = source) => {
+    for (const [token, nodes] of Object.entries(table)) (store.messages[token] ||= Object.create(null))[language] = nodes;
+  };
+  const fetchLanguage = language => {
+    if (store.loaded.has(language)) return Promise.resolve();
+    if (!load) return Promise.reject(new Error(`No loader for ${language}.`));
+    return Promise.resolve(load(language)).then(table => { store.add(table, language); store.loaded.add(language); });
+  };
+  const catalog = { languages };
+  const browser = typeof document !== 'undefined' && typeof navigator !== 'undefined';
+  const storage = (action, value) => {
+    if (!browser || !storageKey) return null;
+    try { return action === 'get' ? localStorage.getItem(storageKey) : localStorage.setItem(storageKey, value); } catch { return null; }
+  };
+  // Only a browser's languages say what the reader wants; Node also has a navigator,
+  // whose language is the server's.
+  const preferred = browser ? [storage('get'), ...(navigator.languages || [navigator.language])] : [];
+  const wanted = preferred.map(l => matchLanguage(catalog, l)).find(Boolean) || source;
+  let current = source;
+  const listeners = new Set();
+  const switchTo = next => {
+    if (next === current) return;
+    current = next;
+    if (browser) document.documentElement.lang = next;
+    for (const listener of listeners) listener(next);
+  };
+  if (browser) document.documentElement.lang = source;
+  // Until the reader's language has loaded, pages render in the source language.
+  const ready = fetchLanguage(wanted).then(() => { switchTo(wanted); return current; }, error => { onError(error); return current; });
+  return {
+    store,
+    ready,
+    getLanguage: () => current,
+    /** Load a language's messages, for i18nmd.in(language) on a server or in tests. */
+    loadLanguage: language => fetchLanguage(matchLanguage(catalog, language) || source),
+    /** Load a language, switch every later call to it and remember it; resolves to the language chosen. */
+    async setLanguage(language) {
+      const next = matchLanguage(catalog, language);
+      if (!next) { onError(new Error(`Unknown language: ${language}`)); return current; }
+      try { await fetchLanguage(next); } catch (error) { onError(error); return current; }
+      storage('set', next);
+      switchTo(next);
+      return current;
+    },
+    /** Call listener with the new language after each change; returns an unsubscribe function. */
+    onLanguageChange(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+  };
+}
+
+/**
+ * The generated i18nmd function over a language's store. Divisions are
+ * properties: i18nmd.support("contact_us") is the token support.contact_us.
+ * i18nmd.in("fr") translates into a given (loaded) language instead, for
+ * servers, emails and tests. divisions maps each property to [segment, children].
+ */
+export function createTranslator(language, divisions = {}, options = {}) {
+  const { store } = language;
+  const onError = options.onError || (error => console.error(`i18nmd: ${error.message}`));
+  const translate = createI18n(store, { ...options, onError: error => {
+    // A token from a division whose module this code never imported.
+    const token = /^Unknown translation token: (.+)$/.exec(error.message)?.[1];
+    const division = token && store.divisions.filter(d => token.startsWith(d.replace(/\//g, '.') + '.')).sort((a, b) => b.length - a.length)[0];
+    onError(division ? new Error(`${token} is in the ${division} division, which this page has not imported. Import i18nmd from its module (i18nmd check --in <src> --fix adds it).`) : error);
+  } });
+  const build = (prefix, tree, fixed) => {
+    const scoped = (token, values) => translate(prefix + token, fixed ?? language.getLanguage(), values);
+    for (const [property, [segment, children]] of Object.entries(tree)) {
+      Object.defineProperty(scoped, property, { value: build(`${prefix}${segment}.`, children, fixed), enumerable: true });
+    }
+    return scoped;
+  };
+  const i18nmd = build('', divisions);
+  Object.defineProperty(i18nmd, 'in', { value: fixed => build('', divisions, fixed), enumerable: false });
+  return i18nmd;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@likolabs/i18nmd",
+  "version": "0.1.1",
+  "description": "Interface strings in Markdown, one file per language. A compiler checks every language and generates typed code your app imports.",
+  "author": "Liko Labs (https://likolabs.com)",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "i18nmd": "bin/i18nmd.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./runtime": "./lib/runtime.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts/python_catalog.py",
+    "README.md",
+    "LICENSE",
+    "PROMPT.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check": "npm test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@babel/parser": "7.29.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/birep/i18n.md.git"
+  },
+  "homepage": "https://i18n.md",
+  "bugs": {
+    "url": "https://github.com/birep/i18n.md/issues"
+  },
+  "keywords": [
+    "i18n",
+    "l10n",
+    "internationalization",
+    "localization",
+    "translation",
+    "icu",
+    "messageformat",
+    "markdown",
+    "react",
+    "typescript",
+    "llm"
+  ],
+  "license": "MIT"
+}

package/scripts/python_catalog.py

@@ -0,0 +1,49 @@
+"""Read literal translation tables with ast; never execute an input module."""
+import ast
+import json
+import string
+import sys
+from pathlib import Path
+
+
+def read_catalog(filename, table_name="_T", languages_name="LANGS"):
+    source = Path(filename).read_text()
+    tree = ast.parse(source)
+    found = {}
+    for node in tree.body:
+        if isinstance(node, (ast.Assign, ast.AnnAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            for target in targets:
+                if isinstance(target, ast.Name) and target.id in (table_name, languages_name):
+                    if target.id in found:
+                        raise ValueError(f"Duplicate assignment to {target.id}")
+                    found[target.id] = ast.literal_eval(node.value)
+    tables = found[table_name]
+    languages = found[languages_name]
+    if not isinstance(tables, dict) or not isinstance(languages, dict) or set(tables) != set(languages):
+        raise ValueError("Translation tables must match the declared languages")
+    source_language = "en" if "en" in tables else next(iter(tables))
+    keys = set(tables[source_language])
+    if any(set(table) != keys for table in tables.values()):
+        raise ValueError("Every language must have the same tokens")
+    formatter = string.Formatter()
+    messages = []
+    for key, value in tables[source_language].items():
+        translations = {lang: table[key] for lang, table in tables.items()}
+        params = {name for _, name, _, _ in formatter.parse(value) if name}
+        optional = set()
+        for text in translations.values():
+            names = {name for _, name, _, _ in formatter.parse(text) if name}
+            if not names <= params:
+                raise ValueError(f"{key}: a translation introduces unknown placeholders")
+            optional |= params - names
+        messages.append({"key": key, "context": f"{Path(filename).name}: {key}", "optional": sorted(optional), "translations": translations})
+    return {"title": "Application strings", "source": source_language, "syntax": "python", "languages": languages, "messages": messages}
+
+
+if __name__ == "__main__":
+    try:
+        print(json.dumps(read_catalog(*sys.argv[1:]), ensure_ascii=False))
+    except (ValueError, KeyError, SyntaxError, OSError) as error:
+        print(str(error), file=sys.stderr)
+        sys.exit(1)