lino-i18n 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # lino-i18n Changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- 8e331fd: Add reactive runtime subscriptions and first-class React bindings with provider,
+  translation hooks, rich interpolation, locale selection, and Intl formatters.
+
+## 0.1.1
+
+### Patch Changes
+
+- 22cf52e: Document the Hive Mind deep catalogue authoring pattern and keep JS examples aligned.
+
+## 0.1.0
+
+### Minor Changes
+
+- 4c3b133: Add configurable compatibility aliases for deeper nested migration keys.
+
+## 0.0.2
+
+### Patch Changes
+
+- 29f0d6f: Preserve scalar parent translations as `label` children when formatting nested
+  catalogues, and resolve `foo` from `foo.label` when no explicit `foo`
+  translation exists.
+
 ## 0.0.1
 
 Initial release of the JavaScript `lino-i18n` package.

package/README.md

@@ -30,18 +30,79 @@ i18n.t('greeting', { name: 'World' }); // → "Hello, World!"
 i18n.t('cart.items', { count: 0 }); // → "Your cart is empty"
 i18n.t('cart.items', { count: 3 }, { locale: 'ru' }); // → "3 товара"
 i18n.t('role', { context: 'female' }); // → "She is a developer"
+i18n.t('telegram.help.solve.alias.detail'); // → "Tool aliases imply `--tool <tool>`"
 ```
 
+## React
+
+React is an optional peer dependency. The `lino-i18n/react` adapter uses the
+same `.lino` catalogues as the framework-independent runtime:
+
+```jsx
+import { createI18n } from 'lino-i18n';
+import {
+  CurrencyFormat,
+  I18nProvider,
+  LocaleSelector,
+  Trans,
+  useTranslation,
+} from 'lino-i18n/react';
+
+const i18n = createI18n({ locales: catalogues, defaultLocale: 'en' });
+
+function Checkout() {
+  const { t } = useTranslation('checkout');
+  return (
+    <>
+      <h1>{t('title')}</h1>
+      <Trans
+        id="checkout.total"
+        values={{ amount: <CurrencyFormat value={19.99} currency="USD" /> }}
+      />
+      <LocaleSelector labels={{ en: 'English', fr: 'Français' }} />
+    </>
+  );
+}
+
+export default function App() {
+  return (
+    <I18nProvider i18n={i18n}>
+      <Checkout />
+    </I18nProvider>
+  );
+}
+```
+
+`useI18n`, `useLocale`, and `useTranslation` update when `setLocale`,
+`addLocale`, or an asynchronous catalogue loader changes the instance.
+`NumberFormat`, `DateTimeFormat`, `CurrencyFormat`, and `RelativeTimeFormat`
+format values with the active locale through the platform `Intl` APIs.
+
 A sample `.lino` catalogue looks like this:
 
 ```lino
 en
   greeting "Hello, {{name}}!"
-  hero
-    description """
-      Keep each language in its own block, nest related messages together,
-      and still resolve the same runtime keys.
-    """
+  telegram
+    help
+      title "Help"
+      solve
+        alias
+          detail "Tool aliases imply `--tool <tool>`"
+  prompt
+    system
+      general
+        guidelines
+          header "General guidelines."
+          body """
+            When you start, create a detailed plan for yourself.
+            Follow your todo list step by step.
+          """
+  error
+    label "Error"
+    invalid
+      github
+        url "Error: Invalid GitHub URL format"
   cart
     title "Your cart"
     items
@@ -54,9 +115,36 @@ en
     other "They are a developer"
 ```
 
-Nested plural and context groups flatten to the runtime suffix keys
-`cart.items_one`, `cart.items_other`, and `role_female`. A single file may also
-contain several top-level locale blocks, for example `en` followed by `ru`.
+Deeply nested blocks flatten to canonical dot keys such as
+`telegram.help.solve.alias.detail` and
+`prompt.system.general.guidelines.body`. Nested plural and context groups still
+flatten to runtime suffix keys such as `cart.items_one`, `cart.items_other`,
+and `role_female`. A single file may also contain several top-level locale
+blocks, for example `en` followed by `ru`.
+
+Use a `label` child when a translated group also needs its own runtime key:
+`error.label` and `error` both resolve to `"Error"`, and an explicit `error`
+translation wins over the generated alias.
+
+For migrations from flatter catalogues, enable compatibility aliases when
+loading or creating the runtime:
+
+```js
+const catalogues = await loadLocalesFromDirectory('./locales', {
+  compatibilityAliases: ['collapseTail', 'parentLabel'],
+});
+const i18n = createI18n({
+  locales: catalogues,
+  defaultLocale: 'en',
+});
+```
+
+`collapseTail` exposes underscore-tail aliases for deeper keys, so
+`telegram.help.solve.alias.detail` also resolves through
+`telegram.help_solve_alias_detail`, `telegram.help.solve_alias_detail`, and
+`telegram.help.solve.alias_detail`. `parentLabel` maps `error.label` to the
+legacy parent key `error`. Generated aliases never overwrite explicit
+translations.
 
 ## CLI
 
@@ -90,7 +178,9 @@ Run `npx lino-i18n --help` for every option.
 - `{{var}}` and `{var}` placeholder syntax for compatibility with i18next
   and `react-intl`.
 - Context (gender) suffixes: `role_male`, `role_female`, `role_other`.
+- Migration aliases for deeper nested keys and parent labels.
 - Namespace prefixes via `:` (`navigation:home`) and `.` (`cart.title`).
+- Group label aliases via `label` children.
 - Configurable fallback chain.
 - Bundled multi-locale `.lino` files and per-language directories.
 - Optional missing-key handler.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lino-i18n",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Universal i18n library that stores translations in Links Notation (.lino) instead of JSON.",
   "type": "module",
   "main": "./src/index.js",
@@ -21,7 +21,11 @@
       "import": "./src/index.js"
     },
     "./converters": "./src/converters/index.js",
-    "./loaders": "./src/loaders.js"
+    "./loaders": "./src/loaders.js",
+    "./react": {
+      "types": "./src/react.d.ts",
+      "import": "./src/react.js"
+    }
   },
   "scripts": {
     "test": "node --test --test-timeout=30000 tests/*.test.js",
@@ -69,11 +73,23 @@
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.17",
     "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
     "jscpd": "^4.2.2",
     "prettier": "^3.8.3",
+    "react": "^19.1.1",
+    "react-test-renderer": "^19.1.1",
     "test-anywhere": "^0.9.1"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }

package/src/compatibility.js

@@ -0,0 +1,85 @@
+// Compatibility helpers for catalogue migrations. These helpers work on the
+// flat key tables produced by the loader and only add aliases for keys that do
+// not already exist.
+
+const ALIAS_NAMES = new Map([
+  ['collapseTail', 'collapseTail'],
+  ['collapse-tail', 'collapseTail'],
+  ['parentLabel', 'parentLabel'],
+  ['parent-label', 'parentLabel'],
+]);
+
+function toAliasList(options = {}) {
+  if (Array.isArray(options) || typeof options === 'string') {
+    return Array.isArray(options) ? options : [options];
+  }
+  const requested = options.compatibilityAliases ?? options.mode ?? [];
+  return Array.isArray(requested) ? requested : [requested];
+}
+
+export function normalizeCompatibilityAliases(options = {}) {
+  const normalized = [];
+  for (const alias of toAliasList(options)) {
+    if (!alias) {
+      continue;
+    }
+    const name = ALIAS_NAMES.get(String(alias));
+    if (!name) {
+      throw new TypeError(`unknown compatibility alias mode: ${alias}`);
+    }
+    if (!normalized.includes(name)) {
+      normalized.push(name);
+    }
+  }
+  return normalized;
+}
+
+function collapseTailAliases(key) {
+  const parts = key.split('.');
+  if (parts.length < 3) {
+    return [];
+  }
+  const aliases = [];
+  for (let index = 1; index < parts.length - 1; index += 1) {
+    aliases.push(
+      `${parts.slice(0, index).join('.')}.${parts.slice(index).join('_')}`
+    );
+  }
+  return aliases;
+}
+
+function parentLabelAlias(key) {
+  if (!key.endsWith('.label')) {
+    return null;
+  }
+  const parent = key.slice(0, -'.label'.length);
+  return parent || null;
+}
+
+export function expandCompatibilityAliases(translations, options = {}) {
+  const aliases = normalizeCompatibilityAliases(options);
+  const expanded = { ...(translations || {}) };
+  if (aliases.length === 0) {
+    return expanded;
+  }
+
+  const hasOwn = Object.prototype.hasOwnProperty;
+  for (const [key, value] of Object.entries(translations || {})) {
+    if (aliases.includes('collapseTail')) {
+      for (const alias of collapseTailAliases(key)) {
+        if (!hasOwn.call(expanded, alias)) {
+          expanded[alias] = value;
+        }
+      }
+    }
+
+    if (aliases.includes('parentLabel')) {
+      const alias = parentLabelAlias(key);
+      if (alias && !hasOwn.call(expanded, alias)) {
+        expanded[alias] = value;
+      }
+    }
+  }
+
+  return expanded;
+}

package/src/format.js

@@ -3,6 +3,7 @@
 // resolution algorithm shared between the runtime and the CLI.
 
 const INTERPOLATION_PATTERN = /\{\{?\s*([\w.$:-]+)\s*\}?\}/g;
+const LABEL_ALIAS_KEY = 'label';
 
 const PLURAL_SUFFIXES = ['zero', 'one', 'two', 'few', 'many', 'other'];
 
@@ -100,6 +101,10 @@ export function resolveKey(table, key, { count, context, locale } = {}) {
     if (direct !== undefined) {
       return direct;
     }
+    const labelAlias = lookup(table, `${target}.${LABEL_ALIAS_KEY}`);
+    if (labelAlias !== undefined) {
+      return labelAlias;
+    }
   }
 
   if (context) {
@@ -112,4 +117,8 @@ export function resolveKey(table, key, { count, context, locale } = {}) {
   return undefined;
 }
 
-export const _internals = { PLURAL_SUFFIXES, INTERPOLATION_PATTERN };
+export const _internals = {
+  PLURAL_SUFFIXES,
+  INTERPOLATION_PATTERN,
+  LABEL_ALIAS_KEY,
+};

package/src/i18n.js

@@ -8,6 +8,10 @@ import {
   loadLocalesFromFile,
   loadLocalesFromDirectory,
 } from './loaders.js';
+import {
+  expandCompatibilityAliases,
+  normalizeCompatibilityAliases,
+} from './compatibility.js';
 import { interpolate, resolveKey } from './format.js';
 
 function normalizeFallbacks(fallback) {
@@ -27,16 +31,46 @@ export function createI18n(options = {}) {
     fallback = ['en'],
     onMissingKey,
     interpolation = { prefix: '{{', suffix: '}}' },
+    compatibilityAliases: requestedCompatibilityAliases = [],
   } = options;
+  const compatibilityAliases = normalizeCompatibilityAliases(
+    requestedCompatibilityAliases
+  );
 
   const catalogues = new Map();
   for (const [locale, translations] of Object.entries(locales)) {
-    catalogues.set(locale, { ...translations });
+    catalogues.set(
+      locale,
+      expandCompatibilityAliases(translations, { compatibilityAliases })
+    );
   }
 
   let currentLocale = defaultLocale;
+  let revision = 0;
+  const listeners = new Set();
   const fallbacks = normalizeFallbacks(fallback);
 
+  function notify() {
+    revision += 1;
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  function subscribe(listener) {
+    if (typeof listener !== 'function') {
+      throw new TypeError('subscribe expects a function');
+    }
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  function getRevision() {
+    return revision;
+  }
+
   function getLocale() {
     return currentLocale;
   }
@@ -45,7 +79,10 @@ export function createI18n(options = {}) {
     if (typeof locale !== 'string' || !locale) {
       throw new TypeError('setLocale expects a non-empty string locale');
     }
-    currentLocale = locale;
+    if (locale !== currentLocale) {
+      currentLocale = locale;
+      notify();
+    }
   }
 
   function getFallbacks() {
@@ -58,7 +95,7 @@ export function createI18n(options = {}) {
 
   function has(key, locale = currentLocale) {
     const table = catalogues.get(locale);
-    return Boolean(table && Object.prototype.hasOwnProperty.call(table, key));
+    return resolveKey(table, key, { locale }) !== undefined;
   }
 
   function _lookup(key, opts) {
@@ -117,7 +154,14 @@ export function createI18n(options = {}) {
       throw new TypeError('addLocale requires a string locale name');
     }
     const current = catalogues.get(locale) || {};
-    catalogues.set(locale, { ...current, ...translations });
+    catalogues.set(
+      locale,
+      expandCompatibilityAliases(
+        { ...current, ...translations },
+        { compatibilityAliases }
+      )
+    );
+    notify();
   }
 
   async function loadLocale(locale, text) {
@@ -157,5 +201,7 @@ export function createI18n(options = {}) {
     loadLocaleFile,
     loadDirectory,
     interpolation,
+    subscribe,
+    getRevision,
   };
 }

package/src/index.d.ts

@@ -1,5 +1,18 @@
 // Type declarations for the `lino-i18n` package.
 
+export type CompatibilityAlias =
+  | 'collapseTail'
+  | 'collapse-tail'
+  | 'parentLabel'
+  | 'parent-label';
+
+export interface CompatibilityAliasOptions {
+  /** Alias modes used to expose migration keys without overwriting explicit keys. */
+  compatibilityAliases?: CompatibilityAlias | CompatibilityAlias[];
+  /** Alias mode shortcut for helper-style calls. */
+  mode?: CompatibilityAlias | CompatibilityAlias[];
+}
+
 export interface I18nOptions {
   /** Translation catalogues keyed by locale code. */
   locales?: Record<string, Record<string, string>>;
@@ -15,6 +28,8 @@ export interface I18nOptions {
   }) => string | void;
   /** Interpolation tokens; currently informational only. */
   interpolation?: { prefix?: string; suffix?: string };
+  /** Compatibility aliases generated from canonical keys during migration. */
+  compatibilityAliases?: CompatibilityAlias | CompatibilityAlias[];
 }
 
 export interface TOptions {
@@ -47,19 +62,39 @@ export interface I18nInstance {
   loadLocaleFile(filePath: string): Promise<string>;
   loadDirectory(directory: string): Promise<string[]>;
   interpolation: { prefix?: string; suffix?: string };
+  subscribe(listener: () => void): () => void;
+  getRevision(): number;
 }
 
 export declare function createI18n(options?: I18nOptions): I18nInstance;
 
+export declare function expandCompatibilityAliases(
+  translations: Record<string, string>,
+  options?: CompatibilityAliasOptions
+): Record<string, string>;
+
 export declare function parseLinoCatalog(text: string): {
   locale: string | null;
   translations: Record<string, string>;
 };
 
+export declare function parseLinoCatalog(
+  text: string,
+  options: CompatibilityAliasOptions
+): {
+  locale: string | null;
+  translations: Record<string, string>;
+};
+
 export declare function parseLinoCatalogs(
   text: string
 ): Array<{ locale: string | null; translations: Record<string, string> }>;
 
+export declare function parseLinoCatalogs(
+  text: string,
+  options: CompatibilityAliasOptions
+): Array<{ locale: string | null; translations: Record<string, string> }>;
+
 export declare function formatLinoCatalog(
   locale: string,
   translations: Record<string, string>,
@@ -75,19 +110,23 @@ export declare function formatLinoCatalogs(
 
 export declare function loadLocaleFromString(
   locale: string,
-  text: string
+  text: string,
+  options?: CompatibilityAliasOptions
 ): Promise<{ locale: string; translations: Record<string, string> }>;
 
 export declare function loadLocaleFromFile(
-  filePath: string
+  filePath: string,
+  options?: CompatibilityAliasOptions
 ): Promise<{ locale: string; translations: Record<string, string> }>;
 
 export declare function loadLocalesFromFile(
-  filePath: string
+  filePath: string,
+  options?: CompatibilityAliasOptions
 ): Promise<Array<{ locale: string; translations: Record<string, string> }>>;
 
 export declare function loadLocalesFromDirectory(
-  directory: string
+  directory: string,
+  options?: CompatibilityAliasOptions
 ): Promise<Record<string, Record<string, string>>>;
 
 export declare function interpolate(

package/src/index.js

@@ -8,6 +8,7 @@
 // framework.
 
 export { createI18n } from './i18n.js';
+export { expandCompatibilityAliases } from './compatibility.js';
 export {
   parseLinoCatalog,
   parseLinoCatalogs,

package/src/loaders.js

@@ -7,6 +7,8 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
+import { expandCompatibilityAliases } from './compatibility.js';
+
 const SELECTOR_SUFFIXES = new Set([
   'zero',
   'one',
@@ -19,6 +21,8 @@ const SELECTOR_SUFFIXES = new Set([
   'neutral',
 ]);
 
+const LABEL_ALIAS_KEY = 'label';
+
 function unescapeValue(value, quote = '"') {
   let result = '';
   for (let index = 0; index < value.length; index += 1) {
@@ -275,7 +279,9 @@ function isPlainObject(value) {
 }
 
 function isSelectorGroup(value) {
-  const entries = Object.entries(value);
+  const entries = Object.entries(value).filter(
+    ([key]) => key !== LABEL_ALIAS_KEY
+  );
   return (
     entries.length > 0 &&
     entries.every(
@@ -284,6 +290,18 @@ function isSelectorGroup(value) {
   );
 }
 
+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)) {
+    out[base] = value;
+  }
+}
+
 function flattenTree(tree, pathParts = [], out = {}) {
   for (const [key, value] of Object.entries(tree)) {
     if (typeof value === 'string') {
@@ -295,14 +313,25 @@ function flattenTree(tree, pathParts = [], out = {}) {
     }
 
     const nextPath = [...pathParts, key];
+    const base = nextPath.join('.');
+    const labelValue = labelAliasValue(value);
     if (isSelectorGroup(value)) {
-      const base = nextPath.join('.');
+      if (labelValue !== undefined) {
+        out[`${base}.${LABEL_ALIAS_KEY}`] = labelValue;
+        addLabelAlias(out, base, labelValue);
+      }
       for (const [suffix, child] of Object.entries(value)) {
+        if (suffix === LABEL_ALIAS_KEY) {
+          continue;
+        }
         out[`${base}_${suffix}`] = child;
       }
       continue;
     }
     flattenTree(value, nextPath, out);
+    if (labelValue !== undefined) {
+      addLabelAlias(out, base, labelValue);
+    }
   }
   return out;
 }
@@ -322,12 +351,23 @@ function splitSelectorSuffix(key) {
 function setNestedValue(tree, parts, value) {
   let node = tree;
   for (const part of parts.slice(0, -1)) {
-    if (!isPlainObject(node[part])) {
+    const current = node[part];
+    if (!isPlainObject(current)) {
       node[part] = {};
+      if (typeof current === 'string') {
+        node[part][LABEL_ALIAS_KEY] = current;
+      }
     }
     node = node[part];
   }
-  node[parts[parts.length - 1]] = value;
+  const leaf = parts[parts.length - 1];
+  if (isPlainObject(node[leaf])) {
+    if (!Object.prototype.hasOwnProperty.call(node[leaf], LABEL_ALIAS_KEY)) {
+      node[leaf][LABEL_ALIAS_KEY] = value;
+    }
+    return;
+  }
+  node[leaf] = value;
 }
 
 function translationsToTree(translations) {
@@ -360,7 +400,12 @@ function formatValue(value, indent) {
 
 function formatTreeLines(tree, indent = '  ') {
   const lines = [];
-  for (const [key, value] of Object.entries(tree)) {
+  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}${key} ${formatValue(value, indent)}`);
       continue;
@@ -386,16 +431,16 @@ function formatFlatCatalog(locale, translations) {
 // 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) {
-  const catalogues = parseLinoCatalogs(text);
+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) {
+export function parseLinoCatalogs(text, options = {}) {
   return parseLocaleTrees(text).map(({ locale, tree }) => ({
     locale: locale || null,
-    translations: flattenTree(tree),
+    translations: expandCompatibilityAliases(flattenTree(tree), options),
   }));
 }
 
@@ -427,8 +472,8 @@ export function formatLinoCatalogs(catalogues, options = {}) {
     .join('\n\n');
 }
 
-export async function loadLocaleFromString(locale, text) {
-  const parsedCatalogues = parseLinoCatalogs(text);
+export async function loadLocaleFromString(locale, text, options = {}) {
+  const parsedCatalogues = parseLinoCatalogs(text, options);
   const parsed = parsedCatalogues.find(
     (catalogue) => catalogue.locale === locale
   ) ||
@@ -439,17 +484,17 @@ export async function loadLocaleFromString(locale, text) {
   };
 }
 
-export async function loadLocaleFromFile(filePath) {
+export async function loadLocaleFromFile(filePath, options = {}) {
   const text = await fs.readFile(filePath, 'utf8');
-  const parsed = parseLinoCatalog(text);
+  const parsed = parseLinoCatalog(text, options);
   const locale =
     parsed.locale || path.basename(filePath, path.extname(filePath));
   return { locale, translations: parsed.translations };
 }
 
-export async function loadLocalesFromFile(filePath) {
+export async function loadLocalesFromFile(filePath, options = {}) {
   const text = await fs.readFile(filePath, 'utf8');
-  const parsed = parseLinoCatalogs(text);
+  const parsed = parseLinoCatalogs(text, options);
   if (parsed.length > 0) {
     return parsed;
   }
@@ -461,7 +506,7 @@ export async function loadLocalesFromFile(filePath) {
   ];
 }
 
-export async function loadLocalesFromDirectory(directory) {
+export async function loadLocalesFromDirectory(directory, options = {}) {
   const entries = (await fs.readdir(directory, { withFileTypes: true })).sort(
     (left, right) => left.name.localeCompare(right.name)
   );
@@ -486,5 +531,8 @@ export async function loadLocalesFromDirectory(directory) {
       };
     }
   }
+  for (const [locale, translations] of Object.entries(catalogues)) {
+    catalogues[locale] = expandCompatibilityAliases(translations, options);
+  }
   return catalogues;
 }

package/src/react.d.ts

@@ -0,0 +1,44 @@
+import type { ReactNode, SelectHTMLAttributes } from 'react';
+import type { I18nInstance, TOptions, TParams } from './index.js';
+
+export declare function I18nProvider(props: {
+  i18n: I18nInstance;
+  children?: ReactNode;
+}): ReactNode;
+export declare function useI18n(): I18nInstance;
+export declare function useLocale(): string;
+export declare function useTranslation(keyPrefix?: string): {
+  t(key: string, params?: TParams, options?: TOptions): string;
+  i18n: I18nInstance;
+  locale: string;
+};
+export declare function Trans(props: {
+  id: string;
+  values?: Record<string, unknown>;
+  options?: TOptions;
+  fallback?: string;
+}): ReactNode;
+export declare function LocaleSelector(
+  props: SelectHTMLAttributes<HTMLSelectElement> & {
+    locales?: string[];
+    labels?: Record<string, ReactNode>;
+  }
+): ReactNode;
+export declare function NumberFormat(props: {
+  value: number | bigint;
+  options?: Intl.NumberFormatOptions;
+}): ReactNode;
+export declare function DateTimeFormat(props: {
+  value: Date | number;
+  options?: Intl.DateTimeFormatOptions;
+}): ReactNode;
+export declare function RelativeTimeFormat(props: {
+  value: number;
+  unit: Intl.RelativeTimeFormatUnit;
+  options?: Intl.RelativeTimeFormatOptions;
+}): ReactNode;
+export declare function CurrencyFormat(props: {
+  value: number | bigint;
+  currency: string;
+  options?: Intl.NumberFormatOptions;
+}): ReactNode;

package/src/react.js

@@ -0,0 +1,120 @@
+import React, {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useSyncExternalStore,
+} from 'react';
+
+const I18nContext = createContext(null);
+
+function useI18nContext() {
+  const i18n = useContext(I18nContext);
+  if (!i18n) {
+    throw new Error(
+      'lino-i18n React hooks must be used inside an I18nProvider'
+    );
+  }
+  useSyncExternalStore(i18n.subscribe, i18n.getRevision, i18n.getRevision);
+  return i18n;
+}
+
+export function I18nProvider({ i18n, children }) {
+  if (!i18n?.t || !i18n?.subscribe) {
+    throw new TypeError('I18nProvider requires a createI18n instance');
+  }
+  return createElement(I18nContext.Provider, { value: i18n }, children);
+}
+
+export function useI18n() {
+  return useI18nContext();
+}
+
+export function useLocale() {
+  return useI18nContext().getLocale();
+}
+
+export function useTranslation(keyPrefix = '') {
+  const i18n = useI18nContext();
+  const t = useCallback(
+    (key, params, options) =>
+      i18n.t(keyPrefix ? `${keyPrefix}.${key}` : key, params, options),
+    [i18n, keyPrefix]
+  );
+  return { t, i18n, locale: i18n.getLocale() };
+}
+
+export function Trans({ id, values = {}, options, fallback }) {
+  const i18n = useI18nContext();
+  const entries = Object.entries(values);
+  const markers = Object.fromEntries(
+    entries.map(([key, value], index) => [
+      key,
+      React.isValidElement(value) ? `\uE000${index}\uE001` : value,
+    ])
+  );
+  const translated = i18n.t(
+    id,
+    { ...markers, defaultValue: fallback },
+    options
+  );
+  if (!entries.some(([, value]) => React.isValidElement(value))) {
+    return translated;
+  }
+  const pattern = /(\uE000\d+\uE001)/g;
+  return translated.split(pattern).map((part, index) => {
+    const match = /^\uE000(\d+)\uE001$/.exec(part);
+    return match
+      ? React.cloneElement(entries[Number(match[1])][1], { key: index })
+      : part;
+  });
+}
+
+export function LocaleSelector({ locales, labels = {}, ...props }) {
+  const i18n = useI18nContext();
+  const available = locales || i18n.listLocales();
+  return createElement(
+    'select',
+    {
+      'aria-label': 'Language',
+      ...props,
+      value: i18n.getLocale(),
+      onChange: (event) => {
+        i18n.setLocale(event.target.value);
+        props.onChange?.(event);
+      },
+    },
+    available.map((locale) =>
+      createElement(
+        'option',
+        { key: locale, value: locale },
+        labels[locale] || locale
+      )
+    )
+  );
+}
+
+function Format({ value, formatter, options }) {
+  const locale = useLocale();
+  return new Intl[formatter](locale, options).format(value);
+}
+
+export function NumberFormat(props) {
+  return createElement(Format, { ...props, formatter: 'NumberFormat' });
+}
+
+export function DateTimeFormat(props) {
+  return createElement(Format, { ...props, formatter: 'DateTimeFormat' });
+}
+
+export function RelativeTimeFormat({ value, unit, options }) {
+  const locale = useLocale();
+  return new Intl.RelativeTimeFormat(locale, options).format(value, unit);
+}
+
+export function CurrencyFormat({ value, currency, options }) {
+  return createElement(NumberFormat, {
+    value,
+    options: { style: 'currency', currency, ...options },
+  });
+}