lino-i18n 0.0.1

package/src/converters/i18n-js.js

@@ -0,0 +1,70 @@
+// Convert i18n-js translation files (Rails-style JSON) into flat lino
+// catalogues. i18n-js uses `%{var}` interpolation; this converter rewrites
+// `%{name}` into `{{name}}` for consistency with the lino-i18n runtime
+// while preserving everything else verbatim.
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function rewriteInterpolation(template) {
+  if (typeof template !== 'string') {
+    return template;
+  }
+  return template.replace(/%\{\s*([\w.-]+)\s*\}/g, '{{$1}}');
+}
+
+function flatten(prefix, value, out) {
+  if (typeof value === 'string') {
+    out[prefix] = rewriteInterpolation(value);
+    return;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    out[prefix] = String(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    out[prefix] = value.map(rewriteInterpolation).join('\n');
+    return;
+  }
+  if (!isPlainObject(value)) {
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const nextKey = prefix ? `${prefix}.${key}` : key;
+    flatten(nextKey, child, out);
+  }
+}
+
+function looksLikeLocale(name) {
+  return /^[a-z]{2,3}([-_][A-Za-z0-9]{2,8})*$/i.test(name);
+}
+
+function looksMultiLocale(input) {
+  if (!isPlainObject(input)) {
+    return false;
+  }
+  const keys = Object.keys(input);
+  if (keys.length === 0) {
+    return false;
+  }
+  return keys.every((key) => looksLikeLocale(key) && isPlainObject(input[key]));
+}
+
+export function fromI18nJs(input, { locale, defaultLocale = 'en' } = {}) {
+  if (!input) {
+    return {};
+  }
+  if (looksMultiLocale(input)) {
+    const result = {};
+    for (const [lc, content] of Object.entries(input)) {
+      const flat = {};
+      flatten('', content, flat);
+      result[lc] = flat;
+    }
+    return result;
+  }
+  const flat = {};
+  flatten('', input, flat);
+  return { [locale || defaultLocale]: flat };
+}

package/src/converters/i18next.js

@@ -0,0 +1,98 @@
+// Convert i18next resource bundles to flat lino catalogues.
+//
+// Input shapes accepted:
+//   1. A single locale: { greeting: 'Hello', cart: { items: '...' } }
+//   2. Multi-locale: { en: {...}, ru: {...} }
+//   3. Multi-locale with namespaces: { en: { common: {...}, cart: {...} } }
+//
+// Notes:
+//   - Nested keys are flattened with `.` (i18next default).
+//   - When a namespace is present, keys are prefixed with `ns:`.
+//   - i18next-style `_one` / `_other` suffixes are preserved verbatim.
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function flatten(prefix, value, out) {
+  if (typeof value === 'string') {
+    out[prefix] = value;
+    return;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    out[prefix] = String(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    out[prefix] = value.join('\n');
+    return;
+  }
+  if (!isPlainObject(value)) {
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const nextKey = prefix ? `${prefix}.${key}` : key;
+    flatten(nextKey, child, out);
+  }
+}
+
+function looksLikeLocale(name) {
+  return /^[a-z]{2,3}([-_][A-Za-z0-9]{2,8})*$/i.test(name);
+}
+
+function looksMultiLocale(input) {
+  if (!isPlainObject(input)) {
+    return false;
+  }
+  const keys = Object.keys(input);
+  if (keys.length === 0) {
+    return false;
+  }
+  return keys.every((key) => looksLikeLocale(key) && isPlainObject(input[key]));
+}
+
+function hasNamespaceShape(localeObj) {
+  if (!isPlainObject(localeObj)) {
+    return false;
+  }
+  const values = Object.values(localeObj);
+  if (values.length === 0) {
+    return false;
+  }
+  return values.every((value) => isPlainObject(value));
+}
+
+function flattenWithOptionalNamespaces(localeObj) {
+  const out = {};
+  if (!isPlainObject(localeObj)) {
+    return out;
+  }
+  const useNamespaces = hasNamespaceShape(localeObj);
+  if (useNamespaces) {
+    for (const [ns, content] of Object.entries(localeObj)) {
+      const nsOut = {};
+      flatten('', content, nsOut);
+      for (const [key, value] of Object.entries(nsOut)) {
+        out[`${ns}:${key}`] = value;
+      }
+    }
+  } else {
+    flatten('', localeObj, out);
+  }
+  return out;
+}
+
+export function fromI18next(input, { locale, defaultLocale = 'en' } = {}) {
+  if (!input) {
+    return {};
+  }
+  if (looksMultiLocale(input)) {
+    const result = {};
+    for (const [lc, content] of Object.entries(input)) {
+      result[lc] = flattenWithOptionalNamespaces(content);
+    }
+    return result;
+  }
+  const chosenLocale = locale || defaultLocale;
+  return { [chosenLocale]: flattenWithOptionalNamespaces(input) };
+}

package/src/converters/index.js

@@ -0,0 +1,10 @@
+// Converters take an external translation source (i18next JSON, i18n-js
+// JSON, react-intl JSON) and return a normalized `{ [locale]: { [key]: value } }`
+// map ready to be serialised by `formatLinoCatalog`.
+
+export { fromI18next } from './i18next.js';
+export { fromI18nJs } from './i18n-js.js';
+export { fromReactIntl } from './react-intl.js';
+export { detectFormat } from './detect.js';
+
+export const SUPPORTED_FORMATS = ['i18next', 'i18n-js', 'react-intl'];

package/src/converters/react-intl.js

@@ -0,0 +1,102 @@
+// Convert react-intl / FormatJS catalogues into flat lino catalogues.
+//
+// react-intl messages can be in two shapes:
+//   1. Compiled AST:   { 'cart.title': [...] }
+//   2. Plain ICU:      { 'cart.title': 'Hello, {name}' }
+//      or extracted:   { 'cart.title': { defaultMessage: 'Hello, {name}' } }
+//
+// This converter:
+//   - Always emits ICU `{var}` placeholders verbatim. The lino-i18n
+//     interpolation engine accepts both `{var}` and `{{var}}`.
+//   - Preserves IDs as keys.
+//   - When given an object of `{ defaultMessage, description }`, it
+//     takes `defaultMessage`.
+//   - Compiled AST messages are decompiled back to ICU when possible.
+
+function decompileAst(ast) {
+  if (typeof ast === 'string') {
+    return ast;
+  }
+  if (!Array.isArray(ast)) {
+    return null;
+  }
+  let out = '';
+  for (const node of ast) {
+    if (typeof node === 'string') {
+      out += node;
+      continue;
+    }
+    if (!node || typeof node !== 'object') {
+      continue;
+    }
+    // FormatJS node shapes: { type: 0, value: 'text' } (literal)
+    // { type: 1, value: 'name' } (argument), etc.
+    if (node.type === 0 && typeof node.value === 'string') {
+      out += node.value;
+    } else if (node.type === 1 && typeof node.value === 'string') {
+      out += `{${node.value}}`;
+    } else if (typeof node.value === 'string') {
+      out += `{${node.value}}`;
+    } else {
+      return null; // cannot represent reliably
+    }
+  }
+  return out;
+}
+
+function normaliseMessage(entry) {
+  if (typeof entry === 'string') {
+    return entry;
+  }
+  if (Array.isArray(entry)) {
+    return decompileAst(entry);
+  }
+  if (entry && typeof entry === 'object') {
+    if (typeof entry.defaultMessage === 'string') {
+      return entry.defaultMessage;
+    }
+    if (typeof entry.message === 'string') {
+      return entry.message;
+    }
+    if (typeof entry.value === 'string') {
+      return entry.value;
+    }
+  }
+  return null;
+}
+
+function isLocaleMap(input) {
+  if (!input || typeof input !== 'object') {
+    return false;
+  }
+  const keys = Object.keys(input);
+  if (keys.length === 0) {
+    return false;
+  }
+  return keys.every((key) => /^[a-z]{2,3}([-_][A-Za-z0-9]{2,8})*$/i.test(key));
+}
+
+export function fromReactIntl(input, { locale, defaultLocale = 'en' } = {}) {
+  if (!input || typeof input !== 'object') {
+    return {};
+  }
+  if (isLocaleMap(input)) {
+    const result = {};
+    for (const [lc, content] of Object.entries(input)) {
+      result[lc] = flatten(content);
+    }
+    return result;
+  }
+  return { [locale || defaultLocale]: flatten(input) };
+}
+
+function flatten(messages) {
+  const out = {};
+  for (const [id, entry] of Object.entries(messages || {})) {
+    const value = normaliseMessage(entry);
+    if (typeof value === 'string') {
+      out[id] = value;
+    }
+  }
+  return out;
+}

package/src/format.js

@@ -0,0 +1,115 @@
+// Pure helpers used by the i18n runtime: interpolation, plural-suffix
+// resolution against `Intl.PluralRules`, context suffixing, and the key
+// resolution algorithm shared between the runtime and the CLI.
+
+const INTERPOLATION_PATTERN = /\{\{?\s*([\w.$:-]+)\s*\}?\}/g;
+
+const PLURAL_SUFFIXES = ['zero', 'one', 'two', 'few', 'many', 'other'];
+
+export function interpolate(template, params) {
+  if (typeof template !== 'string') {
+    return template;
+  }
+  if (!params) {
+    return template;
+  }
+  return template.replace(INTERPOLATION_PATTERN, (match, name) => {
+    if (!Object.prototype.hasOwnProperty.call(params, name)) {
+      return match;
+    }
+    const value = params[name];
+    return value === null || value === undefined ? '' : String(value);
+  });
+}
+
+export function pluralSuffix(locale, count) {
+  if (count === undefined || count === null) {
+    return null;
+  }
+  const numeric = Number(count);
+  if (!Number.isFinite(numeric)) {
+    return null;
+  }
+  try {
+    const rules = new Intl.PluralRules(locale);
+    return rules.select(numeric);
+  } catch {
+    return numeric === 1 ? 'one' : 'other';
+  }
+}
+
+export function applyContext(key, context) {
+  if (!context) {
+    return key;
+  }
+  return `${key}_${context}`;
+}
+
+function lookup(table, key) {
+  if (!table) {
+    return undefined;
+  }
+  if (Object.prototype.hasOwnProperty.call(table, key)) {
+    return table[key];
+  }
+  return undefined;
+}
+
+// Resolve a key inside a flat translation table that may contain dotted
+// keys (e.g., `cart.items`) or namespaced keys (`navigation:home`).
+// Plural-aware: when `count` is present, the function looks up the
+// best CLDR variant from the given locale and falls back to `_other`.
+//
+// Returns `undefined` when the key cannot be resolved. The caller is
+// responsible for fallback handling.
+export function resolveKey(table, key, { count, context, locale } = {}) {
+  if (!table || typeof table !== 'object') {
+    return undefined;
+  }
+  const withContext = context ? applyContext(key, context) : key;
+
+  const targets = context ? [withContext, key] : [withContext];
+
+  for (const target of targets) {
+    if (
+      count !== undefined &&
+      count !== null &&
+      Number.isFinite(Number(count))
+    ) {
+      const numeric = Number(count);
+      if (numeric === 0) {
+        const zeroCandidate = lookup(table, `${target}_zero`);
+        if (zeroCandidate !== undefined) {
+          return zeroCandidate;
+        }
+      }
+      const suffix = pluralSuffix(locale, numeric);
+      if (suffix) {
+        const candidate = lookup(table, `${target}_${suffix}`);
+        if (candidate !== undefined) {
+          return candidate;
+        }
+      }
+      const otherCandidate = lookup(table, `${target}_other`);
+      if (otherCandidate !== undefined) {
+        return otherCandidate;
+      }
+    }
+
+    const direct = lookup(table, target);
+    if (direct !== undefined) {
+      return direct;
+    }
+  }
+
+  if (context) {
+    const otherFallback = lookup(table, `${key}_other`);
+    if (otherFallback !== undefined) {
+      return otherFallback;
+    }
+  }
+
+  return undefined;
+}
+
+export const _internals = { PLURAL_SUFFIXES, INTERPOLATION_PATTERN };

package/src/i18n.js

@@ -0,0 +1,161 @@
+// Runtime engine. Returns an i18n instance with `t`, `setLocale`,
+// `getLocale`, `loadLocale`, `loadLocaleFile`, `loadDirectory`,
+// `getFallbacks`, and `has`. The API is small on purpose: combine it with
+// the framework integrations users already have (React, Vue, etc.).
+
+import {
+  loadLocaleFromString,
+  loadLocalesFromFile,
+  loadLocalesFromDirectory,
+} from './loaders.js';
+import { interpolate, resolveKey } from './format.js';
+
+function normalizeFallbacks(fallback) {
+  if (!fallback) {
+    return [];
+  }
+  if (Array.isArray(fallback)) {
+    return fallback.filter(Boolean).map(String);
+  }
+  return [String(fallback)];
+}
+
+export function createI18n(options = {}) {
+  const {
+    locales = {},
+    defaultLocale = 'en',
+    fallback = ['en'],
+    onMissingKey,
+    interpolation = { prefix: '{{', suffix: '}}' },
+  } = options;
+
+  const catalogues = new Map();
+  for (const [locale, translations] of Object.entries(locales)) {
+    catalogues.set(locale, { ...translations });
+  }
+
+  let currentLocale = defaultLocale;
+  const fallbacks = normalizeFallbacks(fallback);
+
+  function getLocale() {
+    return currentLocale;
+  }
+
+  function setLocale(locale) {
+    if (typeof locale !== 'string' || !locale) {
+      throw new TypeError('setLocale expects a non-empty string locale');
+    }
+    currentLocale = locale;
+  }
+
+  function getFallbacks() {
+    return [...fallbacks];
+  }
+
+  function listLocales() {
+    return Array.from(catalogues.keys());
+  }
+
+  function has(key, locale = currentLocale) {
+    const table = catalogues.get(locale);
+    return Boolean(table && Object.prototype.hasOwnProperty.call(table, key));
+  }
+
+  function _lookup(key, opts) {
+    const tried = [];
+    const locales = [opts?.locale || currentLocale, ...fallbacks];
+    for (const locale of locales) {
+      if (tried.includes(locale)) {
+        continue;
+      }
+      tried.push(locale);
+      const table = catalogues.get(locale);
+      if (!table) {
+        continue;
+      }
+      const value = resolveKey(table, key, {
+        count: opts?.count,
+        context: opts?.context,
+        locale,
+      });
+      if (value !== undefined) {
+        return { value, locale };
+      }
+    }
+    return null;
+  }
+
+  function t(key, params = {}, options = {}) {
+    if (typeof key !== 'string') {
+      return key;
+    }
+    const found = _lookup(key, {
+      count: params.count,
+      context: params.context ?? options.context,
+      locale: options.locale,
+    });
+    if (!found) {
+      if (typeof onMissingKey === 'function') {
+        const fallbackValue = onMissingKey({ key, params, options });
+        if (typeof fallbackValue === 'string') {
+          return interpolate(fallbackValue, params);
+        }
+      }
+      if (params && typeof params.defaultValue === 'string') {
+        return interpolate(params.defaultValue, params);
+      }
+      if (typeof options.defaultValue === 'string') {
+        return interpolate(options.defaultValue, params);
+      }
+      return key;
+    }
+    return interpolate(found.value, params);
+  }
+
+  function addLocale(locale, translations) {
+    if (!locale || typeof locale !== 'string') {
+      throw new TypeError('addLocale requires a string locale name');
+    }
+    const current = catalogues.get(locale) || {};
+    catalogues.set(locale, { ...current, ...translations });
+  }
+
+  async function loadLocale(locale, text) {
+    const parsed = await loadLocaleFromString(locale, text);
+    if (!parsed.locale) {
+      throw new Error('loadLocale could not determine the locale name');
+    }
+    addLocale(parsed.locale, parsed.translations);
+    return parsed.locale;
+  }
+
+  async function loadLocaleFile(filePath) {
+    const loaded = await loadLocalesFromFile(filePath);
+    for (const { locale, translations } of loaded) {
+      addLocale(locale, translations);
+    }
+    return loaded[0]?.locale;
+  }
+
+  async function loadDirectory(directory) {
+    const loaded = await loadLocalesFromDirectory(directory);
+    for (const [locale, translations] of Object.entries(loaded)) {
+      addLocale(locale, translations);
+    }
+    return Object.keys(loaded);
+  }
+
+  return {
+    t,
+    has,
+    getLocale,
+    setLocale,
+    getFallbacks,
+    listLocales,
+    addLocale,
+    loadLocale,
+    loadLocaleFile,
+    loadDirectory,
+    interpolation,
+  };
+}

package/src/index.d.ts

@@ -0,0 +1,122 @@
+// Type declarations for the `lino-i18n` package.
+
+export interface I18nOptions {
+  /** Translation catalogues keyed by locale code. */
+  locales?: Record<string, Record<string, string>>;
+  /** Locale used when no `setLocale` has been called. */
+  defaultLocale?: string;
+  /** Fallback locale (or array of locales) used when a key is missing. */
+  fallback?: string | string[];
+  /** Callback invoked when a key is missing in every locale. */
+  onMissingKey?: (info: {
+    key: string;
+    params: Record<string, unknown>;
+    options: TOptions;
+  }) => string | void;
+  /** Interpolation tokens; currently informational only. */
+  interpolation?: { prefix?: string; suffix?: string };
+}
+
+export interface TOptions {
+  /** Force a specific locale for this call only. */
+  locale?: string;
+  /** Gender / context suffix (resolves `key_context`). */
+  context?: string;
+  /** Default value returned when the key is missing. */
+  defaultValue?: string;
+}
+
+export interface TParams extends Record<string, unknown> {
+  /** Numeric count used for plural resolution. */
+  count?: number;
+  /** Context suffix that overrides `TOptions.context`. */
+  context?: string;
+  /** Default value used when the key is missing. */
+  defaultValue?: string;
+}
+
+export interface I18nInstance {
+  t(key: string, params?: TParams, options?: TOptions): string;
+  has(key: string, locale?: string): boolean;
+  getLocale(): string;
+  setLocale(locale: string): void;
+  getFallbacks(): string[];
+  listLocales(): string[];
+  addLocale(locale: string, translations: Record<string, string>): void;
+  loadLocale(locale: string, text: string): Promise<string>;
+  loadLocaleFile(filePath: string): Promise<string>;
+  loadDirectory(directory: string): Promise<string[]>;
+  interpolation: { prefix?: string; suffix?: string };
+}
+
+export declare function createI18n(options?: I18nOptions): I18nInstance;
+
+export declare function parseLinoCatalog(text: string): {
+  locale: string | null;
+  translations: Record<string, string>;
+};
+
+export declare function parseLinoCatalogs(
+  text: string
+): Array<{ locale: string | null; translations: Record<string, string> }>;
+
+export declare function formatLinoCatalog(
+  locale: string,
+  translations: Record<string, string>,
+  options?: { style?: 'nested' | 'flat' }
+): string;
+
+export declare function formatLinoCatalogs(
+  catalogues:
+    | Record<string, Record<string, string>>
+    | Array<{ locale: string; translations: Record<string, string> }>,
+  options?: { style?: 'nested' | 'flat' }
+): string;
+
+export declare function loadLocaleFromString(
+  locale: string,
+  text: string
+): Promise<{ locale: string; translations: Record<string, string> }>;
+
+export declare function loadLocaleFromFile(
+  filePath: string
+): Promise<{ locale: string; translations: Record<string, string> }>;
+
+export declare function loadLocalesFromFile(
+  filePath: string
+): Promise<Array<{ locale: string; translations: Record<string, string> }>>;
+
+export declare function loadLocalesFromDirectory(
+  directory: string
+): Promise<Record<string, Record<string, string>>>;
+
+export declare function interpolate(
+  template: string,
+  params: Record<string, unknown> | undefined
+): string;
+
+export declare function pluralSuffix(
+  locale: string,
+  count: number
+): string | null;
+
+export declare function resolveKey(
+  table: Record<string, string>,
+  key: string,
+  options?: { count?: number; context?: string; locale?: string }
+): string | undefined;
+
+export declare function fromI18next(
+  input: unknown,
+  options?: { locale?: string; defaultLocale?: string }
+): Record<string, Record<string, string>>;
+
+export declare function fromI18nJs(
+  input: unknown,
+  options?: { locale?: string; defaultLocale?: string }
+): Record<string, Record<string, string>>;
+
+export declare function fromReactIntl(
+  input: unknown,
+  options?: { locale?: string; defaultLocale?: string }
+): Record<string, Record<string, string>>;

package/src/index.js

@@ -0,0 +1,27 @@
+// Public API of the `lino-i18n` package.
+//
+// All translations are stored in Links Notation (.lino) files and parsed
+// through `lino-objects-codec`. The runtime exposed here is intentionally
+// small: it supports the features users expect from i18next / i18n-js /
+// react-intl (interpolation, plurals, namespaces, fallbacks, defaults,
+// missing-key callbacks) without locking us to a specific bundler or
+// framework.
+
+export { createI18n } from './i18n.js';
+export {
+  parseLinoCatalog,
+  parseLinoCatalogs,
+  formatLinoCatalog,
+  formatLinoCatalogs,
+  loadLocaleFromString,
+  loadLocaleFromFile,
+  loadLocalesFromFile,
+  loadLocalesFromDirectory,
+} from './loaders.js';
+export {
+  interpolate,
+  resolveKey,
+  pluralSuffix,
+  applyContext,
+} from './format.js';
+export { fromI18next, fromI18nJs, fromReactIntl } from './converters/index.js';