lino-i18n 0.2.0 → 0.4.0

package/src/browser.d.ts

@@ -0,0 +1,58 @@
+import type {
+  CompatibilityAliasOptions,
+  I18nCoreInstance,
+  I18nOptions,
+} from './index.js';
+
+export type {
+  CompatibilityAlias,
+  CompatibilityAliasOptions,
+  I18nCoreInstance,
+  I18nOptions,
+  TOptions,
+  TParams,
+} from './index.js';
+export {
+  expandCompatibilityAliases,
+  parseLinoCatalog,
+  parseLinoCatalogs,
+  formatLinoCatalog,
+  formatLinoCatalogs,
+  loadLocaleFromString,
+} from './index.js';
+
+export declare function createI18n(options?: I18nOptions): I18nCoreInstance;
+
+export interface LoadCatalogsOptions extends CompatibilityAliasOptions {
+  /** Override the platform fetch, for example in tests. */
+  fetch?: typeof globalThis.fetch;
+  /** Options forwarded to every request, including AbortSignal and cache. */
+  requestInit?: RequestInit;
+}
+
+/** Merge every locale root, with later URLs overriding earlier keys. */
+export declare function loadCatalogs(
+  urls: Array<string | URL>,
+  options?: LoadCatalogsOptions
+): Promise<Record<string, Record<string, string>>>;
+
+export interface LanguageOptions {
+  /** Available catalogue locales; defaults to ['en']. */
+  supportedLanguages?: string[];
+  /** Locale used when no preference matches; defaults to 'en'. */
+  defaultLocale?: string;
+}
+
+/** Match an explicit preference, candidates, then the default or first locale. */
+export declare function resolveLanguage(
+  preference?: string | null,
+  candidates?: string | string[],
+  options?: LanguageOptions
+): string;
+
+/** Read navigator.languages, falling back to navigator.language when empty. */
+export declare function detectLanguage(
+  preference?: string | null,
+  options?: LanguageOptions
+): string;
+export * from './intl.js';

package/src/browser.js

@@ -0,0 +1,58 @@
+// Browser entry point: its entire import graph uses only platform APIs.
+import { parseLinoCatalogs } from './catalogs.js';
+import { expandCompatibilityAliases } from './compatibility.js';
+
+export { createI18n } from './i18n.js';
+export {
+  parseLinoCatalog,
+  parseLinoCatalogs,
+  formatLinoCatalog,
+  formatLinoCatalogs,
+  loadLocaleFromString,
+} from './catalogs.js';
+export { expandCompatibilityAliases } from './compatibility.js';
+export { detectLanguage, resolveLanguage } from './language.js';
+export * from './intl.js';
+
+// Fetch concurrently, then merge in input order. Generate aliases only after
+// merging so a later explicit key always wins over an earlier generated alias.
+export async function loadCatalogs(urls, options = {}) {
+  const { fetch: fetchCatalog = globalThis.fetch, requestInit } = options;
+  if (typeof fetchCatalog !== 'function') {
+    throw new Error('loadCatalogs requires fetch');
+  }
+  const loaded = await Promise.all(
+    urls.map(async (url) => {
+      try {
+        const response = await fetchCatalog(url, requestInit);
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
+        }
+        return parseLinoCatalogs(await response.text());
+      } catch (cause) {
+        throw new Error(
+          `Failed to load catalog ${url}: ${cause?.message ?? String(cause)}`,
+          {
+            cause,
+          }
+        );
+      }
+    })
+  );
+
+  const catalogues = new Map();
+  for (const entries of loaded) {
+    for (const { locale, translations } of entries) {
+      catalogues.set(locale, {
+        ...catalogues.get(locale),
+        ...translations,
+      });
+    }
+  }
+  return Object.fromEntries(
+    Array.from(catalogues, ([locale, translations]) => [
+      locale,
+      expandCompatibilityAliases(translations, options),
+    ])
+  );
+}

package/src/catalogs.js

@@ -0,0 +1,512 @@
+// Loaders translate `.lino` text or files into the flat translation
+// tables consumed by the runtime. The authoring format is an i18n-focused
+// subset of indented Links Notation: each top-level block is a locale, nested
+// blocks become dotted keys, and plural/context selector blocks become
+// underscore suffixes such as `cart.items_one` and `role_female`.
+
+import { expandCompatibilityAliases } from './compatibility.js';
+
+const SELECTOR_SUFFIXES = new Set([
+  'zero',
+  'one',
+  'two',
+  'few',
+  'many',
+  'other',
+  'male',
+  'female',
+  'neutral',
+]);
+
+const LABEL_ALIAS_KEY = 'label';
+
+function setEntry(object, key, value) {
+  Object.defineProperty(object, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  });
+}
+
+function unescapeValue(value, quote = '"') {
+  let result = '';
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (char !== '\\') {
+      result += char;
+      continue;
+    }
+    index += 1;
+    const next = value[index];
+    if (next === undefined || next === '\\') {
+      result += '\\';
+    } else if (next === 'n') {
+      result += '\n';
+    } else if (next === 'r') {
+      result += '\r';
+    } else if (next === 't') {
+      result += '\t';
+    } else if (next === quote) {
+      result += quote;
+    } else {
+      result += `\\${next}`;
+    }
+  }
+  return result;
+}
+
+function escapeValue(value) {
+  return value
+    .split('\\')
+    .join('\\\\')
+    .split('"')
+    .join('\\"')
+    .split('\r')
+    .join('\\r')
+    .split('\t')
+    .join('\\t');
+}
+
+function formatKey(key) {
+  return !key || /[\s"'\\:#]/.test(key)
+    ? `"${escapeValue(key).replaceAll('\n', '\\n')}"`
+    : key;
+}
+
+function splitKey(line) {
+  if (line.startsWith('"') || line.startsWith("'")) {
+    const quote = line[0];
+    const closing = findClosingQuote(line, quote);
+    if (
+      closing === -1 ||
+      (line[closing + 1] && !/\s/.test(line[closing + 1]))
+    ) {
+      throw new Error('Malformed quoted catalog key');
+    }
+    return [
+      unescapeValue(line.slice(1, closing), quote),
+      line.slice(closing + 1).trimStart() || undefined,
+    ];
+  }
+  const match = /^(\S+)(?:\s+(.*))?$/.exec(line);
+  const key =
+    match[2] === undefined && match[1].endsWith(':')
+      ? match[1].slice(0, -1)
+      : match[1];
+  return [key, match[2]?.trimStart()];
+}
+
+function countIndent(line) {
+  let count = 0;
+  for (const char of line) {
+    if (char === ' ') {
+      count += 1;
+    } else if (char === '\t') {
+      count += 2;
+    } else {
+      break;
+    }
+  }
+  return count;
+}
+
+function stripContentIndent(line, indent) {
+  let remaining = indent;
+  let index = 0;
+  while (index < line.length && remaining > 0) {
+    const char = line[index];
+    if (char === ' ') {
+      remaining -= 1;
+      index += 1;
+    } else if (char === '\t') {
+      remaining -= 2;
+      index += 1;
+    } else {
+      break;
+    }
+  }
+  return line.slice(index);
+}
+
+function findClosingQuote(value, quote, start = 1) {
+  let escaped = false;
+  for (let index = start; index < value.length; index += 1) {
+    const char = value[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (char === quote) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function parseTripleQuotedValue(lines, index, rest, indent) {
+  const sameLine = rest.slice(3);
+  if (sameLine.trim()) {
+    const closing = sameLine.lastIndexOf('"""');
+    if (closing !== -1) {
+      return {
+        value: sameLine.slice(0, closing),
+        nextIndex: index + 1,
+      };
+    }
+  }
+
+  const valueLines = [];
+  const contentIndent = indent + 2;
+  for (let current = index + 1; current < lines.length; current += 1) {
+    const raw = lines[current].replace(/\r$/, '');
+    if (raw.trim() === '"""') {
+      return {
+        value: valueLines.join('\n'),
+        nextIndex: current + 1,
+      };
+    }
+    valueLines.push(stripContentIndent(raw, contentIndent));
+  }
+  throw new Error('unterminated multiline string');
+}
+
+function parseQuotedValue(lines, index, rest, indent) {
+  if (rest.startsWith('"""')) {
+    return parseTripleQuotedValue(lines, index, rest, indent);
+  }
+
+  const quote = rest[0];
+  const closing = findClosingQuote(rest, quote);
+  if (closing !== -1) {
+    return {
+      value: unescapeValue(rest.slice(1, closing), quote),
+      nextIndex: index + 1,
+    };
+  }
+
+  const chunks = [rest.slice(1)];
+  for (let current = index + 1; current < lines.length; current += 1) {
+    const raw = lines[current].replace(/\r$/, '');
+    const lineClosing = findClosingQuote(raw, quote, 0);
+    if (lineClosing !== -1) {
+      chunks.push(raw.slice(0, lineClosing));
+      return {
+        value: unescapeValue(chunks.join('\n'), quote),
+        nextIndex: current + 1,
+      };
+    }
+    chunks.push(raw);
+  }
+  throw new Error('unterminated quoted string');
+}
+
+function parseLogicalLines(text) {
+  const lines = String(text || '')
+    .replace(/\r\n/g, '\n')
+    .split('\n');
+  const entries = [];
+  for (let index = 0; index < lines.length;) {
+    const raw = lines[index].replace(/\r$/, '');
+    const content = raw.trimEnd();
+    if (!content.trim() || content.trimStart().startsWith('#')) {
+      index += 1;
+      continue;
+    }
+
+    const indent = countIndent(content);
+    const trimmed = content.trimStart();
+    const [key, rest] = splitKey(trimmed);
+
+    if (rest === undefined) {
+      entries.push({ indent, key, value: null });
+      index += 1;
+      continue;
+    }
+
+    if (rest.startsWith('"') || rest.startsWith("'")) {
+      const parsed = parseQuotedValue(lines, index, rest, indent);
+      entries.push({ indent, key, value: parsed.value });
+      index = parsed.nextIndex;
+      continue;
+    }
+
+    entries.push({ indent, key, value: unescapeValue(rest.trim()) });
+    index += 1;
+  }
+  return entries;
+}
+
+function parseEntriesAt(lines, start, indent) {
+  const tree = {};
+  let index = start;
+
+  while (index < lines.length) {
+    const line = lines[index];
+    if (line.indent < indent) {
+      break;
+    }
+    if (line.indent > indent) {
+      throw new Error(`unexpected indentation before ${line.key}`);
+    }
+
+    index += 1;
+    if (line.value !== null) {
+      setEntry(tree, line.key, line.value);
+      continue;
+    }
+
+    if (index < lines.length && lines[index].indent > line.indent) {
+      const parsed = parseEntriesAt(lines, index, lines[index].indent);
+      setEntry(tree, line.key, parsed.tree);
+      index = parsed.index;
+    } else {
+      setEntry(tree, line.key, {});
+    }
+  }
+
+  return { tree, index };
+}
+
+function parseLocaleTrees(text) {
+  const lines = parseLogicalLines(text);
+  const catalogues = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const root = lines[index];
+    if (root.indent !== 0) {
+      throw new Error(`expected a locale root before ${root.key}`);
+    }
+    if (root.value !== null) {
+      throw new Error(`locale root ${root.key} cannot have a direct value`);
+    }
+
+    index += 1;
+    let tree = {};
+    if (index < lines.length && lines[index].indent > root.indent) {
+      const parsed = parseEntriesAt(lines, index, lines[index].indent);
+      tree = parsed.tree;
+      index = parsed.index;
+    }
+    catalogues.push({ locale: root.key, tree });
+  }
+
+  return catalogues;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isSelectorGroup(value) {
+  const entries = Object.entries(value).filter(
+    ([key]) => key !== LABEL_ALIAS_KEY
+  );
+  return (
+    entries.length > 0 &&
+    entries.every(
+      ([key, child]) => SELECTOR_SUFFIXES.has(key) && typeof child === 'string'
+    )
+  );
+}
+
+function labelAliasValue(value) {
+  return typeof value[LABEL_ALIAS_KEY] === 'string'
+    ? value[LABEL_ALIAS_KEY]
+    : undefined;
+}
+
+function addLabelAlias(out, base, value) {
+  if (!Object.prototype.hasOwnProperty.call(out, base)) {
+    setEntry(out, base, value);
+  }
+}
+
+function flattenTree(tree, pathParts = [], out = {}) {
+  for (const [key, value] of Object.entries(tree)) {
+    if (typeof value === 'string') {
+      setEntry(out, [...pathParts, key].join('.'), value);
+      continue;
+    }
+    if (!isPlainObject(value)) {
+      continue;
+    }
+
+    const nextPath = [...pathParts, key];
+    const base = nextPath.join('.');
+    const labelValue = labelAliasValue(value);
+    if (isSelectorGroup(value)) {
+      if (labelValue !== undefined) {
+        setEntry(out, `${base}.${LABEL_ALIAS_KEY}`, labelValue);
+        addLabelAlias(out, base, labelValue);
+      }
+      for (const [suffix, child] of Object.entries(value)) {
+        if (suffix === LABEL_ALIAS_KEY) {
+          continue;
+        }
+        setEntry(out, `${base}_${suffix}`, child);
+      }
+      continue;
+    }
+    flattenTree(value, nextPath, out);
+    if (labelValue !== undefined) {
+      addLabelAlias(out, base, labelValue);
+    }
+  }
+  return out;
+}
+
+function splitSelectorSuffix(key) {
+  const index = key.lastIndexOf('_');
+  if (index <= 0) {
+    return null;
+  }
+  const suffix = key.slice(index + 1);
+  if (!SELECTOR_SUFFIXES.has(suffix)) {
+    return null;
+  }
+  return { base: key.slice(0, index), suffix };
+}
+
+function setNestedValue(tree, parts, value) {
+  let node = tree;
+  for (const part of parts.slice(0, -1)) {
+    const current = Object.hasOwn(node, part) ? node[part] : undefined;
+    if (!isPlainObject(current)) {
+      setEntry(node, part, {});
+      if (typeof current === 'string') {
+        node[part][LABEL_ALIAS_KEY] = current;
+      }
+    }
+    node = node[part];
+  }
+  const leaf = parts[parts.length - 1];
+  if (Object.hasOwn(node, leaf) && isPlainObject(node[leaf])) {
+    if (!Object.prototype.hasOwnProperty.call(node[leaf], LABEL_ALIAS_KEY)) {
+      node[leaf][LABEL_ALIAS_KEY] = value;
+    }
+    return;
+  }
+  setEntry(node, leaf, value);
+}
+
+function translationsToTree(translations) {
+  const tree = {};
+  for (const [rawKey, rawValue] of Object.entries(translations || {})) {
+    const key = String(rawKey);
+    const value = typeof rawValue === 'string' ? rawValue : String(rawValue);
+    const selector = splitSelectorSuffix(key);
+    if (selector) {
+      setNestedValue(
+        tree,
+        [...selector.base.split('.'), selector.suffix],
+        value
+      );
+    } else {
+      setNestedValue(tree, key.split('.'), value);
+    }
+  }
+  return tree;
+}
+
+function formatValue(value, indent) {
+  if (value.includes('\n')) {
+    const contentIndent = `${indent}  `;
+    const lines = value.split('\n').map((line) => `${contentIndent}${line}`);
+    return `"""\n${lines.join('\n')}\n${indent}"""`;
+  }
+  return `"${escapeValue(value)}"`;
+}
+
+function formatTreeLines(tree, indent = '  ') {
+  const lines = [];
+  const entries = Object.entries(tree);
+  const labelEntry = entries.find(([key]) => key === LABEL_ALIAS_KEY);
+  const orderedEntries = labelEntry
+    ? [labelEntry, ...entries.filter(([key]) => key !== LABEL_ALIAS_KEY)]
+    : entries;
+  for (const [key, value] of orderedEntries) {
+    if (typeof value === 'string') {
+      lines.push(`${indent}${formatKey(key)} ${formatValue(value, indent)}`);
+      continue;
+    }
+    if (!isPlainObject(value)) {
+      continue;
+    }
+    lines.push(`${indent}${formatKey(key)}`);
+    lines.push(...formatTreeLines(value, `${indent}  `));
+  }
+  return lines;
+}
+
+function formatFlatCatalog(locale, translations) {
+  const lines = [String(locale)];
+  for (const [key, value] of Object.entries(translations || {})) {
+    const safe = typeof value === 'string' ? value : String(value);
+    lines.push(`  ${formatKey(key)} ${formatValue(safe, '  ')}`);
+  }
+  return lines.join('\n');
+}
+
+// Parse the contents of one `.lino` catalogue. Returns the first
+// `{ locale, translations }` pair when the file contains multiple locale
+// roots. Use `parseLinoCatalogs` to keep every root.
+export function parseLinoCatalog(text, options = {}) {
+  const catalogues = parseLinoCatalogs(text, options);
+  return catalogues[0] || { locale: null, translations: {} };
+}
+
+// Parse every top-level locale block in a `.lino` string.
+export function parseLinoCatalogs(text, options = {}) {
+  return parseLocaleTrees(text).map(({ locale, tree }) => ({
+    locale: locale || null,
+    translations: expandCompatibilityAliases(flattenTree(tree), options),
+  }));
+}
+
+// Format a flat translation table as indented Links Notation. The default
+// output is nested for readability; pass `{ style: 'flat' }` to emit one
+// key/value line per translation.
+export function formatLinoCatalog(locale, translations, options = {}) {
+  if (!locale) {
+    throw new Error('formatLinoCatalog requires a locale name');
+  }
+  if (options.style === 'flat') {
+    return formatFlatCatalog(locale, translations);
+  }
+  const lines = [String(locale)];
+  lines.push(...formatTreeLines(translationsToTree(translations)));
+  return lines.join('\n');
+}
+
+export function formatLinoCatalogs(catalogues, options = {}) {
+  const entries = Array.isArray(catalogues)
+    ? catalogues.map(({ locale, translations }) => [locale, translations])
+    : Object.entries(catalogues || {}).sort(([left], [right]) =>
+        left.localeCompare(right)
+      );
+  return entries
+    .map(([locale, translations]) =>
+      formatLinoCatalog(locale, translations, options)
+    )
+    .join('\n\n');
+}
+
+// The public async API converts parse errors to Promise rejections.
+// eslint-disable-next-line require-await
+export async function loadLocaleFromString(locale, text, options = {}) {
+  const parsedCatalogues = parseLinoCatalogs(text, options);
+  const parsed = parsedCatalogues.find(
+    (catalogue) => catalogue.locale === locale
+  ) ||
+    parsedCatalogues[0] || { locale: null, translations: {} };
+  return {
+    locale: locale || parsed.locale,
+    translations: parsed.translations,
+  };
+}

package/src/compiler.d.ts

@@ -0,0 +1,53 @@
+export interface JSXTransformOptions {
+  file?: string;
+  autoText?: boolean;
+  attributes?: string[];
+  components?: Record<string, string[]>;
+  attributeTranslator?: string;
+  serverTranslator?: string;
+}
+export interface TransformedSource {
+  code: string;
+  map: {
+    version: number;
+    sources: string[];
+    sourcesContent?: Array<string | null>;
+    names: string[];
+    mappings: string;
+  } | null;
+}
+export declare function transformJSX(
+  code: string,
+  options?: JSXTransformOptions
+): TransformedSource;
+export declare function createExtractionPlugin(options?: {
+  locale?: string;
+  catalogFile?: string;
+  manifestFile?: string;
+  transform?: JSXTransformOptions;
+}): {
+  name: string;
+  enforce: 'pre';
+  buildStart(): void;
+  transform(
+    this: { error(message: string): never },
+    code: string,
+    id: string
+  ): TransformedSource | null;
+  generateBundle(this: {
+    error(message: string): never;
+    emitFile(asset: {
+      type: 'asset';
+      fileName: string;
+      source: string;
+    }): unknown;
+    resolve?(
+      source: string,
+      importer: string,
+      options: { skipSelf: true }
+    ): Promise<{
+      id: string;
+      external?: boolean | 'absolute' | 'relative';
+    } | null>;
+  }): Promise<void>;
+};