lino-i18n 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # lino-i18n Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- f73aa48: Add a tree-shakeable browser entry point with URL-based Links Notation catalog loading, navigator language detection, and the shared translation runtime.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -33,6 +33,64 @@ i18n.t('role', { context: 'female' }); // → "She is a developer"
 i18n.t('telegram.help.solve.alias.detail'); // → "Tool aliases imply `--tool <tool>`"
 ```
 
+## Browser
+
+Import `lino-i18n/browser` for native ES modules or browser bundles. This
+entry point has no Node built-ins and uses the same translation engine and
+`t(key, params, options)` API as the main entry point:
+
+```js
+import { createI18n, detectLanguage, loadCatalogs } from 'lino-i18n/browser';
+
+const locales = await loadCatalogs(['/locales/en.lino', '/locales/ru.lino']);
+const i18n = createI18n({
+  locales,
+  defaultLocale: detectLanguage('auto', {
+    supportedLanguages: Object.keys(locales),
+    defaultLocale: 'en',
+  }),
+  fallback: ['en'],
+});
+
+i18n.t('greeting', { name: 'Ada' });
+i18n.setLocale('ru');
+i18n.t('greeting', { name: 'Ada' });
+```
+
+`loadCatalogs(urls, options)` fetches URLs concurrently and merges every locale
+root in URL order. Later catalogs override earlier values for matching keys.
+It returns locale tables ready for `createI18n`; errors reject the promise and
+identify the failing URL. `options.requestInit` forwards fetch options such as
+`cache`, `credentials`, and `signal`. `options.fetch` overrides the platform
+fetch, and `options.compatibilityAliases` enables migration aliases after merging.
+
+`detectLanguage(preference, options)` checks an explicit preference first, then
+`navigator.languages` in preference order. It uses `navigator.language` when
+the language list is empty. `resolveLanguage(preference, candidates, options)`
+performs the same matching with a supplied list, without reading the navigator.
+Both accept `supportedLanguages` (default `['en']`) and `defaultLocale` (default
+`'en'`). Tags are compared without case sensitivity, underscores become hyphens,
+and exact tags are tried before parent tags (`pt-BR` before `pt`). An unsupported
+preference or `'auto'` defers to candidates, then the default locale, then the
+first supported locale. With no supported locales, the default is returned.
+Detection also works in environments without a navigator.
+
+The browser instance includes `subscribe`, `addLocale`, and `loadLocale` and
+works with `lino-i18n/react`. File methods `loadLocaleFile` and `loadDirectory`
+are available through the main entry point. URL loading stays explicit: fetch
+more catalogs with `loadCatalogs`, then register their tables with `addLocale`.
+ES module exports and `sideEffects: false` let bundlers remove unused helpers.
+For TypeScript browser hooks, pass the exported `I18nCoreInstance` type to
+`useI18n<I18nCoreInstance>()` or `useTranslation<I18nCoreInstance>()`. Their
+default type preserves the main entry point's existing file-loading API.
+
+Run the static browser example from `js/`:
+
+```bash
+node examples/browser-usage/server.mjs
+# Open http://127.0.0.1:4173/examples/browser-usage/
+```
+
 ## React
 
 React is an optional peer dependency. The `lino-i18n/react` adapter uses the
@@ -191,6 +249,9 @@ Run `npx lino-i18n --help` for every option.
 
 ```bash
 npm test           # node --test --test-timeout=30000 tests/*.test.js
+npm run test:types # browser and React TypeScript API checks
+npx playwright install chromium
+npm run test:browser # real browser catalog loading and runtime language switching
 ```
 
 ## License

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "lino-i18n",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Universal i18n library that stores translations in Links Notation (.lino) instead of JSON.",
   "type": "module",
+  "sideEffects": false,
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "bin": {
@@ -22,6 +23,10 @@
     },
     "./converters": "./src/converters/index.js",
     "./loaders": "./src/loaders.js",
+    "./browser": {
+      "types": "./src/browser.d.ts",
+      "import": "./src/browser.js"
+    },
     "./react": {
       "types": "./src/react.d.ts",
       "import": "./src/react.js"
@@ -29,6 +34,8 @@
   },
   "scripts": {
     "test": "node --test --test-timeout=30000 tests/*.test.js",
+    "test:browser": "playwright test",
+    "test:types": "tsc --project tests/types/tsconfig.json",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
@@ -73,8 +80,10 @@
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.63.0",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",
+    "esbuild": "^0.28.2",
     "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
@@ -82,7 +91,8 @@
     "prettier": "^3.8.3",
     "react": "^19.1.1",
     "react-test-renderer": "^19.1.1",
-    "test-anywhere": "^0.9.1"
+    "test-anywhere": "^0.9.1",
+    "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "react": ">=18.0.0"

package/src/browser.d.ts

@@ -0,0 +1,57 @@
+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;

package/src/browser.js

@@ -0,0 +1,57 @@
+// 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';
+
+// 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),
+    ])
+  );
+}