lino-i18n 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

package/README.md

@@ -33,6 +33,51 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lino-i18n",
-  "version": "0.1.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/i18n.js

@@ -46,8 +46,31 @@ export function createI18n(options = {}) {
   }
 
   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;
   }
@@ -56,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() {
@@ -135,6 +161,7 @@ export function createI18n(options = {}) {
         { compatibilityAliases }
       )
     );
+    notify();
   }
 
   async function loadLocale(locale, text) {
@@ -174,5 +201,7 @@ export function createI18n(options = {}) {
     loadLocaleFile,
     loadDirectory,
     interpolation,
+    subscribe,
+    getRevision,
   };
 }

package/src/index.d.ts

@@ -62,6 +62,8 @@ 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;

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 },
+  });
+}