@likolabs/i18nmd 0.1.1

package/lib/extractor.mjs

@@ -0,0 +1,362 @@
+import { parse, parseExpression } from '@babel/parser';
+import { escapeMessageLiteral } from './messages.mjs';
+import { languageName, accessorFor } from './catalog.mjs';
+
+const attributes = new Set(['alt', 'title', 'placeholder', 'aria-label', 'aria-description', 'label']);
+const sourcePlugins = ['jsx', 'typescript'];
+
+// Readable tokens from the words of the message; a numeric suffix resolves collisions.
+// Tokens never encode the text, so editing the source message keeps the token.
+function tokenFor(text, taken) {
+  const words = text.toLowerCase().replace(/\{[^}]+\}|<\/?[\w-]+>/g, ' ').normalize('NFKD').replace(/[\u0300-\u036f]/g, '').split(/[^a-z0-9]+/).filter(Boolean);
+  let slug = '';
+  for (const word of words) { if (slug && slug.length + word.length >= 40) break; slug += (slug ? '_' : '') + word; }
+  slug = slug.slice(0, 40) || 'message';
+  if (/^\d/.test(slug)) slug = 'n' + slug;
+  let key = slug;
+  for (let n = 2; taken.has(key); n++) key = `${slug}_${n}`;
+  return key;
+}
+
+const countLike = /^(?:n|num|count|total|qty|quantity|amount|size|length|\w*count|num\w*|\w*total)$/i;
+const inlineAttributes = new Set(['className', 'class', 'href', 'to', 'target', 'rel', 'style', 'id', 'key', 'lang', 'dir']);
+
+// A short element such as <b>, <a href>, or <Link to> inside a sentence becomes an ICU tag.
+function inlineElement(child) {
+  if (child.type !== 'JSXElement' || child.openingElement.selfClosing || child.openingElement.name.type !== 'JSXIdentifier') return false;
+  if (!child.openingElement.attributes.every(a => a.type === 'JSXAttribute' && inlineAttributes.has(a.name?.name))) return false;
+  return child.children.length > 0 && child.children.every(c => c.type === 'JSXText' || c.type === 'JSXExpressionContainer' && (c.expression.type === 'StringLiteral' || valueExpression(c.expression)));
+}
+
+function describe(node) {
+  const name = node?.type === 'JSXOpeningElement' ? node.name : node?.openingElement?.name;
+  return name?.type === 'JSXIdentifier' ? `<${name.name}>` : name ? 'element' : 'fragment';
+}
+
+// React's JSX line whitespace rules, applied before moving text to a catalog.
+function jsxText(value) {
+  const lines = value.split(/\r\n|\n|\r/);
+  let last = 0;
+  for (let i = 0; i < lines.length; i++) if (/[^ \t]/.test(lines[i])) last = i;
+  return lines.map((line, i) => {
+    let text = line.replace(/\t/g, ' ');
+    if (i !== 0) text = text.replace(/^ +/, '');
+    if (i !== lines.length - 1) text = text.replace(/ +$/, '');
+    return text ? text + (i !== last ? ' ' : '') : '';
+  }).join('');
+}
+
+function safeExpression(node) {
+  return node?.type === 'Identifier' || node?.type === 'MemberExpression' && !node.computed && safeExpression(node.object) && node.property.type === 'Identifier';
+}
+
+function containsJsx(node) {
+  if (!node || typeof node !== 'object') return false;
+  if (node.type === 'JSXElement' || node.type === 'JSXFragment') return true;
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'loc' || key.endsWith('Comments')) continue;
+    if (Array.isArray(value) ? value.some(containsJsx) : value && typeof value.type === 'string' && containsJsx(value)) return true;
+  }
+  return false;
+}
+
+// An expression inside a sentence that renders a value, not markup: it becomes a
+// placeholder so the sentence stays whole. Anything that renders elements ends the sentence.
+function valueExpression(node) {
+  return node && node.type !== 'JSXEmptyExpression' && node.type !== 'StringLiteral' && !containsJsx(node);
+}
+
+const formatting = /^(?:to(?:Lower|Upper|Locale(?:Lower|Upper)?)Case|toString|toFixed|toPrecision|toLocaleString|trim\w*|padStart|padEnd|join|format)$/;
+
+// A placeholder name a translator can understand, from the expression that fills it:
+// item.name → name, formatLength(kerf) → kerf, LABELS[item.kind].toLowerCase() → kind,
+// rows.length → rowsCount.
+function placeholderName(node) {
+  switch (node?.type) {
+    case 'Identifier': return node.name;
+    case 'MemberExpression': case 'OptionalMemberExpression':
+      // LABELS[item.kind] → kind; parts.split(" ")[0] → parts.
+      if (node.computed) return placeholderName(node.property) || placeholderName(node.object);
+      if (node.property.name === 'length' && placeholderName(node.object)) return `${placeholderName(node.object)}Count`;
+      return node.property.name;
+    case 'CallExpression': case 'OptionalCallExpression': {
+      const callee = node.callee;
+      if (callee.type?.endsWith('MemberExpression') && !callee.computed && (formatting.test(callee.property.name) || /^(?:split|slice|substring|replace\w*|at|get|find)$/.test(callee.property.name))) return placeholderName(callee.object);
+      if (node.arguments.length && placeholderName(node.arguments[0])) return placeholderName(node.arguments[0]);
+      return callee.type?.endsWith('MemberExpression') ? callee.property.name : placeholderName(callee);
+    }
+    case 'TSNonNullExpression': case 'TSAsExpression': case 'ParenthesizedExpression': return placeholderName(node.expression);
+    case 'LogicalExpression': return placeholderName(node.left);
+    case 'ConditionalExpression': return placeholderName(['StringLiteral', 'TemplateLiteral'].includes(node.consequent.type) ? node.test : node.consequent);
+    case 'BinaryExpression': return placeholderName(node.left);
+    case 'UnaryExpression': return placeholderName(node.argument);
+    default: return undefined;
+  }
+}
+
+// Spaces and list separators (" · ", " | ", " — ") at a message's edges are layout,
+// not wording: they stay in the code so translations need not reproduce them.
+function splitEdges(text) {
+  const [, lead, body, trail] = /^(\s*(?:[·•|—–-]\s+)?)([\s\S]*?)((?:\s+[·•|—–-])?\s*)$/.exec(text);
+  return [lead, body, trail];
+}
+
+// Concatenation is text only when a string takes part; {index + 1} is arithmetic.
+const concatenatesText = node => node.type === 'BinaryExpression' && node.operator === '+' && [node.left, node.right].some(n => n.type === 'StringLiteral' || n.type === 'TemplateLiteral' || concatenatesText(n));
+const textChoice = node => node.type === 'ConditionalExpression' && [node.consequent, node.alternate].some(n => n.type === 'StringLiteral' || n.type === 'TemplateLiteral') || node.type === 'TemplateLiteral' || concatenatesText(node);
+
+export function extractSource(source, options = {}) {
+  const { filename = 'Component.tsx', locale = 'en', importPath = './i18n', languageExpression, existing, namespace = '' } = options;
+  // Without a language expression, calls use the current language (setLanguage).
+  if (languageExpression !== undefined) {
+    const languageNode = parseExpression(languageExpression, { plugins: sourcePlugins });
+    if (!safeExpression(languageNode) && languageNode.type !== 'StringLiteral') throw new Error('The language expression must be a string, variable, or property access.');
+  }
+  const callee = `i18nmd${languageExpression === undefined ? '' : `.in(${languageExpression})`}${accessorFor(namespace)}`;
+  const ast = parse(source, { sourceType: 'unambiguous', plugins: sourcePlugins });
+  const catalog = existing ? structuredClone(existing) : { title: 'Application strings', source: locale, syntax: 'icu', languages: { [locale]: languageName(locale) }, messages: [] };
+  if (catalog.syntax !== 'icu' || catalog.source !== locale) throw new Error('JSX extraction needs an ICU catalog with the matching source language.');
+  const byText = new Map(catalog.messages.map(m => [m.translations[locale], m]));
+  const byKey = new Map(catalog.messages.map(m => [m.key, m]));
+  const edits = [], diagnostics = [];
+  let needsImport = false;
+  const consumed = new WeakSet();
+  const covered = node => consumed.has(node);
+  const callFor = (text, params, node, explicit, where) => {
+    // /* i18n:ui.save */ in code is ## save in the ui division's file.
+    if (namespace && explicit?.startsWith(namespace)) explicit = explicit.slice(namespace.length);
+    let message = explicit ? byKey.get(explicit) : byText.get(text);
+    if (message && message.translations[locale] !== text) throw new Error(`Token ${message.key} already has different source text.`);
+    if (!message) {
+      const key = explicit || tokenFor(text, byKey);
+      if (byKey.has(key)) throw new Error(`Token collision for ${key}. Set an explicit token with /* i18n:token_name */.`);
+      message = { key, context: `${where} (${filename}:${node.loc.start.line})`, optional: [], translations: { [locale]: text } };
+      catalog.messages.push(message); byText.set(text, message); byKey.set(key, message);
+    }
+    needsImport = true;
+    for (const [name] of params) if (countLike.test(name) && !/\{\s*\w+\s*,\s*(plural|number|selectordinal)/.test(text)) diagnostics.push(`${filename}:${node.loc.start.line}: {${name}} looks like a count; consider {${name}, plural, one {…} other {…}} in ${message.key}.`);
+    const values = params.length ? `, { ${params.map(([name, value]) => `${name}: ${value}`).join(', ')} }` : '';
+    return `${callee}(${JSON.stringify(message.key)}${values})`;
+  };
+  // A template literal as a message: each ${…} becomes a named placeholder.
+  const templateMessage = node => {
+    const params = [];
+    const text = node.quasis.map((q, i) => {
+      if (q.value.cooked == null) throw new Error(`${filename}:${node.loc.start.line}: invalid template escape.`);
+      let part = escapeMessageLiteral(q.value.cooked);
+      if (i < node.expressions.length) {
+        const expression = node.expressions[i];
+        if (containsJsx(expression)) throw new Error(`${filename}:${node.loc.start.line}: a template placeholder cannot render elements.`);
+        let name = /^[a-zA-Z_]\w*$/.test(placeholderName(expression) || '') ? placeholderName(expression) : 'value';
+        while (params.some(p => p[0] === name)) name += '_';
+        params.push([name, source.slice(expression.start, expression.end)]);
+        part += `{${name}}`;
+      }
+      return part;
+    }).join('');
+    return { text, params };
+  };
+  // Wording chosen in code, {busy ? "Saving…" : "Save"}, becomes one message per
+  // branch; the condition stays in code. Returns false for text it cannot convert.
+  const convertText = (node, where) => {
+    switch (node.type) {
+      case 'StringLiteral': case 'TemplateLiteral': {
+        const literal = node.type === 'StringLiteral' ? node.value : node.quasis.map(q => q.value.cooked ?? '').join('');
+        if (!/\p{L}/u.test(literal)) return true;
+        let { text, params } = node.type === 'StringLiteral' ? { text: escapeMessageLiteral(node.value), params: [] } : templateMessage(node);
+        const [lead, body, trail] = splitEdges(text);
+        const call = callFor(body, params, node, undefined, where);
+        edits.push({ start: node.start, end: node.end, text: lead || trail ? `\`${lead}\${${call}}${trail}\`` : call });
+        consumed.add(node);
+        return true;
+      }
+      case 'ConditionalExpression': return [convertText(node.consequent, where), convertText(node.alternate, where)].every(Boolean);
+      case 'LogicalExpression': return node.operator === '&&' ? convertText(node.right, where) : [convertText(node.left, where), convertText(node.right, where)].every(Boolean);
+      case 'TSAsExpression': case 'ParenthesizedExpression': return convertText(node.expression, where);
+      case 'BinaryExpression': return !concatenatesText(node);
+      default: return true;
+    }
+  };
+  function walk(node, parent) {
+    if (!node || typeof node.type !== 'string' || covered(node)) return;
+    if (node.type === 'JSXElement' || node.type === 'JSXFragment') {
+      const children = node.children;
+      for (let i = 0; i < children.length;) {
+        const start = i;
+        let text = '', literalText = '', params = [], used = new Map();
+        const unique = base => { let name = /^[a-zA-Z_]\w*$/.test(base || '') && base !== '__proto__' ? base : 'value'; while (params.some(p => p[0] === name)) name += '_'; return name; };
+        const choices = [];
+        const piece = child => {
+          if (child.type === 'JSXText') { const value = jsxText(child.value); literalText += value; return escapeMessageLiteral(value); }
+          const expr = child.expression;
+          if (expr.type === 'StringLiteral') { literalText += expr.value; return escapeMessageLiteral(expr.value); }
+          const value = source.slice(expr.start, expr.end);
+          let name = used.get(value);
+          if (!name) {
+            name = unique(placeholderName(expr)); used.set(value, name); params.push([name, value]);
+            if (textChoice(expr)) choices.push(`${filename}:${expr.loc.start.line}: {${name}} is text chosen in code; move the wording into the message as {${name}, select, …} or a plural.`);
+          }
+          return `{${name}}`;
+        };
+        let outside = '';
+        while (i < children.length) {
+          const child = children[i];
+          if (child.type === 'JSXText' || child.type === 'JSXExpressionContainer' && (child.expression.type === 'StringLiteral' || valueExpression(child.expression))) {
+            const before = literalText.length; text += piece(child); outside += literalText.slice(before); i++; continue;
+          }
+          if (inlineElement(child)) {
+            const opening = child.openingElement, tag = unique(opening.name.name.toLowerCase().replace(/[^a-z0-9]/g, '') || 'tag');
+            const inner = child.children.map(piece).join('');
+            const open = source.slice(opening.start, opening.name.end) + (opening.attributes.some(a => a.name.name === 'key') ? '' : ` key=${JSON.stringify(tag)}`) + source.slice(opening.name.end, opening.end);
+            params.push([tag, `chunks => ${open}{chunks}${source.slice(child.closingElement.start, child.closingElement.end)}`]);
+            text += `<${tag}>${inner}</${tag}>`; i++; continue;
+          }
+          break;
+        }
+        // Text with no letters (numbers, symbols, punctuation between values) is not translated.
+        if (i > start && /\p{L}/u.test(outside)) {
+          const first = children[start], last = children[i - 1];
+          // Spaces at the edges separate the message from neighbouring elements; they stay in the code.
+          const [lead, body, trail] = splitEdges(text);
+          const space = ws => ws ? `{${JSON.stringify(ws)}}` : '';
+          edits.push({ start: first.start, end: last.end, text: `${space(lead)}{${callFor(body, params, first, undefined, `Text in ${describe(node)}`)}}${space(trail)}` });
+          diagnostics.push(...choices);
+          for (let index = start; index < i; index++) consumed.add(children[index]);
+        }
+        // Wording chosen in code with nothing around it: each branch becomes its own message.
+        else if (choices.length) {
+          for (let index = start; index < i; index++) {
+            const child = children[index];
+            if (child.type !== 'JSXExpressionContainer' || !textChoice(child.expression)) continue;
+            if (!convertText(child.expression, `Text in ${describe(node)}`)) diagnostics.push(`${filename}:${child.loc.start.line}: dynamic JSX text needs an explicit /* i18n */ message.`);
+          }
+        }
+        if (i === start) {
+          const child = children[i];
+          if (child.type === 'JSXExpressionContainer' && child.expression.type !== 'JSXEmptyExpression' && !safeExpression(child.expression) && !['JSXElement', 'JSXFragment'].includes(child.expression.type)) {
+            // Existing translation calls and structural expressions need no conversion.
+            if (child.expression.type === 'TemplateLiteral' || child.expression.type === 'BinaryExpression') diagnostics.push(`${filename}:${child.loc.start.line}: dynamic JSX text needs an explicit /* i18n */ message.`);
+          }
+          i++;
+        }
+      }
+    }
+    if (node.type === 'JSXAttribute' && attributes.has(node.name?.name) && node.value?.type === 'StringLiteral' && /\p{L}/u.test(node.value.value)) {
+      edits.push({ start: node.value.start, end: node.value.end, text: `{${callFor(escapeMessageLiteral(node.value.value), [], node, undefined, `${node.name.name} attribute of ${describe(parent)}`)}}` });
+      consumed.add(node.value);
+    }
+    const comment = node.leadingComments?.find(c => /^\s*i18n(?:\s|:|$)/.test(c.value));
+    if (comment && ['StringLiteral', 'TemplateLiteral'].includes(node.type) && parent?.type !== 'JSXAttribute' && parent?.type !== 'JSXExpressionContainer') {
+      const { text, params } = node.type === 'StringLiteral' ? { text: escapeMessageLiteral(node.value), params: [] } : templateMessage(node);
+      const explicit = /i18n:\s*([\w.-]+)/.exec(comment.value)?.[1];
+      edits.push({ start: node.start, end: node.end, text: callFor(text, params, node, explicit, 'Annotated string') });
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (['loc', 'leadingComments', 'trailingComments', 'innerComments', 'comments', 'tokens'].includes(key)) continue;
+      if (Array.isArray(value)) for (const child of value) walk(child, node);
+      else if (value && typeof value === 'object') walk(value, node);
+    }
+  }
+  walk(ast);
+  const pieces = [];
+  let cursor = 0;
+  edits.sort((a, b) => a.start - b.start);
+  for (const edit of edits) {
+    pieces.push(source.slice(cursor, edit.start), edit.text);
+    cursor = edit.end;
+  }
+  pieces.push(source.slice(cursor));
+  let rewritten = pieces.join('');
+  if (needsImport) {
+    // i18nmd may already come from another division's module beside ours; this
+    // division's messages then need a plain import of its module.
+    const sibling = source => source.replace(/[^/]*$/, '') === importPath.replace(/[^/]*$/, '');
+    let hasImport = false, otherDivision = false;
+    const imported = new Set(ast.program.body.filter(node => node.type === 'ImportDeclaration').map(node => node.source.value));
+    for (const node of ast.program.body) {
+      if (node.type === 'ImportDeclaration') for (const specifier of node.specifiers) {
+        if (specifier.local.name !== 'i18nmd') continue;
+        if (specifier.type !== 'ImportSpecifier' || specifier.imported.name !== 'i18nmd' || (node.source.value !== importPath && !sibling(node.source.value))) throw new Error('i18nmd is already imported from a different module.');
+        hasImport = true;
+        otherDivision = node.source.value !== importPath;
+      }
+    }
+    if (otherDivision && !imported.has(importPath)) {
+      const last = ast.program.body.filter(node => node.type === 'ImportDeclaration').at(-1);
+      rewritten = rewritten.slice(0, last.end) + `\nimport ${JSON.stringify(importPath)};` + rewritten.slice(last.end);
+    }
+    // Refuse a local binding collision instead of silently changing its meaning.
+    function checkBindings(node) {
+      if (!node || typeof node !== 'object') return;
+      const declarations = node.type === 'VariableDeclarator' ? [node.id] : /Function/.test(node.type || '') ? [node.id, ...(node.params || [])] : node.type === 'ClassDeclaration' ? [node.id] : [];
+      const containsName = value => value && (value.type === 'Identifier' ? value.name === 'i18nmd' : Object.values(value).some(v => Array.isArray(v) ? v.some(containsName) : v && typeof v === 'object' && containsName(v)));
+      if (declarations.some(containsName)) throw new Error('A local i18nmd binding would shadow the generated translation import. Rename it first.');
+      for (const [key, value] of Object.entries(node)) if (!key.includes('Comments') && key !== 'loc') {
+        if (Array.isArray(value)) value.forEach(checkBindings); else if (value && typeof value === 'object') checkBindings(value);
+      }
+    }
+    checkBindings(ast.program);
+    if (!hasImport) {
+      const position = ast.program.directives.at(-1)?.end ?? ast.program.interpreter?.end ?? 0;
+      rewritten = rewritten.slice(0, position) + `${position ? '\n' : ''}import { i18nmd } from ${JSON.stringify(importPath)};\n` + rewritten.slice(position);
+    }
+  }
+  // Parse the result too; transformations must always produce valid TSX.
+  parse(rewritten, { sourceType: 'unambiguous', plugins: sourcePlugins });
+  return { source: rewritten, catalog, diagnostics, replacements: edits.length };
+}
+
+/**
+ * The divisions a file's i18nmd calls use but whose generated modules it does not
+ * import. accessors maps each division's property chain (".knowledgeHub.faq") to
+ * its module name ("knowledge-hub.faq"); namespaces maps token prefixes
+ * ("knowledge-hub.faq.") to the same. fix: the source with the missing imports
+ * added. used: the full tokens the file calls by name; dynamic: calls whose token
+ * is computed, so used may be incomplete.
+ */
+export function missingDivisionImports(source, { accessors, namespaces, filename = 'file.tsx' }) {
+  let ast;
+  try { ast = parse(source, { sourceType: 'unambiguous', plugins: sourcePlugins }); }
+  catch (error) { throw new Error(`${filename}: ${error.message}`); }
+  const imports = ast.program.body.filter(node => node.type === 'ImportDeclaration');
+  const from = imports.find(node => node.specifiers.some(s => s.local.name === 'i18nmd'));
+  const dir = from ? from.source.value.replace(/[^/]*$/, '') : '';
+  const present = new Set(imports.filter(node => dir && node.source.value.startsWith(dir)).map(node => node.source.value.slice(dir.length).replace(/\.(?:[cm]?[jt]s|tsx?)$/, '')));
+  const needed = new Map(), used = new Set();
+  let dynamic = 0;
+  const prefixOf = Object.fromEntries(Object.entries(namespaces).map(([prefix, file]) => [file, prefix]));
+  const visit = node => {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'CallExpression') {
+      // i18nmd.a.b(…) or i18nmd.in(x).a.b(…): the chain after i18nmd (and .in(x)).
+      const chain = [];
+      let callee = node.callee;
+      while (callee?.type === 'MemberExpression' && !callee.computed) { chain.unshift(callee.property.name); callee = callee.object; }
+      if (callee?.type === 'CallExpression' && callee.callee.type === 'MemberExpression' && callee.callee.property.name === 'in') callee = callee.callee.object;
+      // i18nmd.in(locale) itself picks a language; the call on its result translates.
+      if (callee?.type === 'Identifier' && callee.name === 'i18nmd' && !(chain.length === 1 && chain[0] === 'in')) {
+        let division, prefix = '';
+        const first = node.arguments[0];
+        if (chain.length && chain[0] !== 'in') {
+          // The chain names the whole division only when every property is one.
+          division = accessors['.' + chain.join('.')];
+          prefix = division ? prefixOf[division] : '';
+          for (let n = chain.length - 1; n > 0 && !division; n--) division = accessors['.' + chain.slice(0, n).join('.')];
+        } else if (!chain.length && first?.type === 'StringLiteral') {
+          division = Object.keys(namespaces).filter(p => first.value.startsWith(p)).sort((a, b) => b.length - a.length).map(p => namespaces[p])[0];
+        }
+        if (first?.type === 'StringLiteral') used.add(prefix + first.value); else if (first) dynamic++;
+        if (division && !needed.has(division)) needed.set(division, node.loc.start.line);
+      }
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'loc' || key.endsWith('Comments')) continue;
+      if (Array.isArray(value)) value.forEach(visit); else if (value && typeof value.type === 'string') visit(value);
+    }
+  };
+  visit(ast.program);
+  const missing = !from ? [] : [...needed].filter(([division]) => !present.has(division)).map(([division, line]) => ({ division, line, statement: `import ${JSON.stringify(dir + division)};` }));
+  const last = imports.at(-1);
+  const fix = missing.length ? source.slice(0, last.end) + missing.map(m => `\n${m.statement}`).join('') + source.slice(last.end) : source;
+  return { missing, fix, used, dynamic };
+}

package/lib/index.mjs

@@ -0,0 +1,8 @@
+export { parseCatalog, serializeCatalog, validateCatalog, parseLanguageFiles, languageFromFilename, divisionOf, namespaceFor, renameToken } from './catalog.mjs';
+export { compileCatalog, generateModule } from './compiler.mjs';
+export { extractSource } from './extractor.mjs';
+export { createI18n } from './runtime.mjs';
+export { report, syncLock, readLock, serializeLock } from './lock.mjs';
+export { llmConfig, translateLanguage } from './llm.mjs';
+export { resolveLanguage, topLanguages, RANKED } from './languages.mjs';
+export { importMessages, exportMessages } from './interop.mjs';

package/lib/interop.mjs

@@ -0,0 +1,134 @@
+// Convert between i18nmd catalogs and the JSON message files other libraries use.
+//   formatjs  – react-intl / FormatJS: flat {id: "ICU"} or {id: {defaultMessage, description}}
+//   next-intl – nested objects of ICU strings
+//   i18next   – nested objects, {{placeholders}}, plural suffixes such as key_one / key_other
+import { escapeMessageLiteral, parseMessage } from './messages.mjs';
+
+export const FORMATS = ['formatjs', 'next-intl', 'i18next'];
+const PLURAL = ['zero', 'one', 'two', 'few', 'many', 'other'];
+const TOKEN = /^[a-zA-Z_]\w*(?:[.-]\w+)*$/;
+
+function flatten(object, prefix = '', out = {}) {
+  for (const [key, value] of Object.entries(object)) {
+    const name = prefix ? `${prefix}.${key}` : key;
+    if (value && typeof value === 'object' && !Array.isArray(value) && !('defaultMessage' in value)) flatten(value, name, out);
+    else out[name] = value;
+  }
+  return out;
+}
+
+function nest(flat) {
+  const root = {};
+  for (const [key, value] of Object.entries(flat)) {
+    const parts = key.split('.');
+    let node = root;
+    for (const part of parts.slice(0, -1)) {
+      if (typeof node[part] === 'string') throw new Error(`${key} conflicts with the message ${part}; use flat output.`);
+      node = node[part] ||= {};
+    }
+    node[parts.at(-1)] = value;
+  }
+  return root;
+}
+
+function checkToken(key) {
+  if (!TOKEN.test(key)) throw new Error(`"${key}" cannot be an i18nmd token. Tokens use letters, digits, _ . and -.`);
+  return key;
+}
+
+// i18next "Hello {{name}}" → ICU "Hello {name}"; literal text is ICU-escaped.
+function fromI18nextText(text, warnings, key, pound) {
+  let out = '', last = 0;
+  for (const match of text.matchAll(/\{\{\s*-?\s*([\w.]+)\s*(?:,[^}]*)?\}\}|\$t\(([^)]*)\)/g)) {
+    out += escapeMessageLiteral(text.slice(last, match.index));
+    if (match[2] !== undefined) { warnings.push(`${key}: nested $t(${match[2]}) is kept as text.`); out += escapeMessageLiteral(match[0]); }
+    else if (pound && match[1] === 'count') out += '#';
+    else { const name = match[1].replace(/\./g, '_'); if (name !== match[1]) warnings.push(`${key}: {{${match[1]}}} renamed {${name}}.`); out += `{${name}}`; }
+    last = match.index + match[0].length;
+  }
+  return out + escapeMessageLiteral(text.slice(last));
+}
+
+/** Read one locale's JSON into [{key, context, text}]. */
+export function importMessages(json, format, warnings = []) {
+  if (!FORMATS.includes(format)) throw new Error(`--from must be one of ${FORMATS.join(', ')}.`);
+  const flat = flatten(json);
+  const messages = [];
+  if (format !== 'i18next') {
+    for (const [key, value] of Object.entries(flat)) {
+      const text = typeof value === 'string' ? value : value?.defaultMessage;
+      if (typeof text !== 'string') { warnings.push(`${key}: not a message; skipped.`); continue; }
+      parseMessage(text);
+      messages.push({ key: checkToken(key), context: typeof value === 'object' && value.description ? String(value.description) : '', text });
+    }
+    return messages;
+  }
+  const groups = new Map();
+  for (const [key, value] of Object.entries(flat)) {
+    if (typeof value !== 'string') { warnings.push(`${key}: not a string; skipped.`); continue; }
+    const plural = /^(.*)_(zero|one|two|few|many|other|plural)$/.exec(key);
+    const base = plural ? plural[1] : key;
+    if (!groups.has(base)) groups.set(base, {});
+    groups.get(base)[plural ? (plural[2] === 'plural' ? 'other' : plural[2]) : ''] = value;
+  }
+  for (const [key, forms] of groups) {
+    const categories = PLURAL.filter(c => c in forms);
+    let text;
+    if (!categories.length) text = fromI18nextText(forms[''], warnings, key);
+    else {
+      if (!('other' in forms)) forms.other = forms.one ?? forms[''] ?? forms[categories[0]];
+      // i18next v3 used key (singular) + key_plural; the bare key is then "one".
+      if ('' in forms && !('one' in forms)) forms.one = forms[''];
+      text = `{count, plural, ${PLURAL.filter(c => c in forms).map(c => `${c === 'zero' ? '=0' : c} {${fromI18nextText(forms[c], warnings, key, true)}}`).join(' ')}}`;
+    }
+    parseMessage(text);
+    messages.push({ key: checkToken(key), context: '', text });
+  }
+  return messages;
+}
+
+// ICU nodes back to i18next text; returns undefined when i18next cannot express it.
+function toI18nextText(nodes, pound) {
+  let out = '';
+  for (const n of nodes) {
+    if (typeof n === 'string') out += n;
+    else if (n.type === 'argument') out += `{{${n.name}}}`;
+    else if (n.type === 'pound' && pound) out += `{{${pound}}}`;
+    else if (n.type === 'tag') { const inner = toI18nextText(n.children, pound); if (inner === undefined) return; out += `<${n.name}>${inner}</${n.name}>`; }
+    else return;
+  }
+  return out;
+}
+
+/** Turn one language of a catalog into the library's JSON object. */
+export function exportMessages(catalog, locale, format, warnings = []) {
+  if (!FORMATS.includes(format)) throw new Error(`--to must be one of ${FORMATS.join(', ')}.`);
+  const flat = {};
+  for (const message of catalog.messages) {
+    const text = message.translations[locale];
+    if (text === undefined) continue;
+    if (format === 'formatjs') { flat[message.key] = text; continue; }
+    if (format === 'next-intl') { flat[message.key] = text; continue; }
+    const nodes = parseMessage(text, catalog.syntax);
+    const simple = toI18nextText(nodes);
+    if (simple !== undefined) { flat[message.key] = simple; continue; }
+    const [only] = nodes;
+    if (nodes.length === 1 && only.type === 'plural' && !only.offset) {
+      const forms = {};
+      for (const [category, branch] of Object.entries(only.options)) {
+        const suffix = category === '=0' ? 'zero' : PLURAL.includes(category) ? category : undefined;
+        const converted = suffix && toI18nextText(branch, only.name);
+        if (converted === undefined) { forms.failed = true; break; }
+        forms[suffix] = converted;
+      }
+      if (!forms.failed) {
+        if (only.name !== 'count') warnings.push(`${message.key}: i18next selects plurals by count; pass { count: ${only.name} }.`);
+        for (const [suffix, value] of Object.entries(forms)) flat[`${message.key}_${suffix}`] = value.replaceAll(`{{${only.name}}}`, '{{count}}');
+        continue;
+      }
+    }
+    warnings.push(`${message.key}: kept as ICU; load it with the i18next-icu plugin.`);
+    flat[message.key] = text;
+  }
+  return format === 'formatjs' ? flat : nest(flat);
+}

package/lib/languages.mjs

@@ -0,0 +1,58 @@
+import { languageName } from './catalog.mjs';
+
+// Written interface languages ranked by total (first + second language) speakers,
+// after Ethnologue estimates. Approximate; varieties that are rarely written in
+// software interfaces are left out. Used by `i18nmd --top <n>`.
+export const RANKED = [
+  'en', 'zh', 'hi', 'es', 'fr', 'ar', 'bn', 'pt', 'ru', 'ur',
+  'id', 'de', 'ja', 'pcm', 'mr', 'te', 'tr', 'ta', 'vi', 'fil',
+  'ko', 'fa', 'ha', 'sw', 'jv', 'it', 'pa', 'gu', 'th', 'kn',
+  'am', 'pl', 'yo', 'ml', 'or', 'my', 'uk', 'uz', 'ig', 'nl',
+  'ro', 'ne', 'si', 'az', 'ms', 'el', 'cs', 'hu', 'sv', 'zu',
+];
+
+const EXTRA = ['zh-Hans', 'zh-Hant', 'pt-BR', 'pt-PT', 'es-419', 'fr-CA', 'en-GB', 'yue', 'haw', 'nv', 'chr', 'tlh', 'mi', 'sm', 'to', 'qu', 'gn', 'ay', 'yi', 'eo', 'la'];
+const fold = text => text.normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+
+let index;
+function names() {
+  if (index) return index;
+  index = new Map();
+  const english = new Intl.DisplayNames(['en'], { type: 'language', fallback: 'none' });
+  const codes = new Set([...RANKED, ...EXTRA]);
+  for (let a = 97; a <= 122; a++) for (let b = 97; b <= 122; b++) codes.add(String.fromCharCode(a, b));
+  for (const code of codes) {
+    let name;
+    try { name = english.of(code); } catch { continue; }
+    if (!name || name === code) continue;
+    for (const key of [name, languageName(code)]) if (!index.has(fold(key))) index.set(fold(key), code);
+  }
+  // Common shorthand that Intl spells differently.
+  for (const [alias, code] of [['chinese', 'zh'], ['mandarin', 'zh'], ['cantonese', 'yue'], ['farsi', 'fa'], ['tagalog', 'fil'], ['filipino', 'fil'], ['brazilian portuguese', 'pt-BR'], ['latin american spanish', 'es-419'], ['nigerian pidgin', 'pcm'], ['hawaiian', 'haw'], ['navajo', 'nv'], ['klingon', 'tlh']]) index.set(alias, code);
+  return index;
+}
+
+/**
+ * Resolve "french", "Français", "fr" or "pt-BR" to a language code and a name in
+ * that language. Anything unrecognized, such as "pirate", becomes a custom
+ * language whose code is its slug; the translator is asked to write in that style.
+ */
+export function resolveLanguage(input) {
+  const raw = input.trim();
+  try {
+    const [canonical] = Intl.getCanonicalLocales(raw);
+    const name = new Intl.DisplayNames(['en'], { type: 'language', fallback: 'none' }).of(canonical);
+    if (name && name !== canonical && /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/.test(raw)) return { code: canonical, name: languageName(canonical), english: name, custom: false };
+  } catch { /* Not a language tag; try names. */ }
+  const code = names().get(fold(raw));
+  if (code) return { code, name: languageName(code), english: new Intl.DisplayNames(['en'], { type: 'language' }).of(code), custom: false };
+  const slug = fold(raw).replace(/ /g, '-');
+  if (!/^[a-z][a-z0-9-]*$/.test(slug)) throw new Error(`Cannot name a language file for "${input}".`);
+  return { code: slug, name: raw[0].toUpperCase() + raw.slice(1), english: raw, custom: true };
+}
+
+export function topLanguages(n) {
+  if (!Number.isInteger(n) || n < 1) throw new Error('--top needs a positive whole number.');
+  if (n > RANKED.length) throw new Error(`--top supports up to ${RANKED.length} languages.`);
+  return RANKED.slice(0, n);
+}