@mfeflow/i18n 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @mfeflow/i18n
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Internationalisation for micro-frontends. The shell owns one i18next instance; each remote lazy-loads its own namespace from its own deploy. It sets `lang` and `dir` (RTL) on `<html>` and persists the chosen language.
+
+## Install
+
+```sh
+pnpm add @mfeflow/i18n i18next react-i18next react
+```
+
+`i18next` (26), `react-i18next` (17) and `react` (19) are peer dependencies. All three are required, even if you only use the root entry: it registers `react-i18next` with the i18next instance.
+
+## Usage
+
+In the shell, once, before rendering:
+
+```ts
+import { initI18n } from '@mfeflow/i18n';
+
+await initI18n({
+  languages: [
+    { code: 'en', label: 'English' },
+    { code: 'ar', label: 'العربية' },
+  ],
+  defaultLanguage: 'en',
+  resources: { en: { shell: { title: 'Store' } } },
+});
+```
+
+In a remote:
+
+```tsx
+import { useMfeTranslation } from '@mfeflow/i18n/react';
+
+function Cart() {
+  const { t, ready } = useMfeTranslation('cart', (lng) => import(`./i18n/${lng}.json`));
+  return ready ? <h1>{t('title')}</h1> : null;
+}
+```
+
+`useLanguage()` returns the current language, the configured list and `setLanguage(code)` for a picker.
+
+## Module Federation sharing
+
+Bucket: **singleton**. This package keeps page-wide state, so the shell and every remote must use one copy. `@mfeflow/rsbuild` shares it as a Module Federation singleton by default (`createShellConfig` and `createRemoteConfig`); if you configure sharing by hand, mark it `singleton: true`.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { type i18n as I18n, type Resource } from 'i18next';
+import { type MfeStorage } from '@mfeflow/storage';
+export type { I18n };
+export interface LanguageOption {
+    /** BCP 47 code, e.g. `en`, `hi`, `ar`, `pt-BR`. */
+    code: string;
+    /** Shown in language pickers, in that language: `English`, `हिन्दी`, `العربية`. */
+    label: string;
+}
+export interface InitI18nOptions {
+    languages: readonly LanguageOption[];
+    defaultLanguage: string;
+    /** Messages the shell ships up front. Remotes load their own with `loadNamespace`. */
+    resources?: Resource;
+    /** Use the browser's languages when nothing is stored. Default true. */
+    detect?: boolean;
+    /** Defaults to the shell's storage. */
+    storage?: MfeStorage;
+    /** Gets `lang` and `dir`. Defaults to `<html>`. */
+    root?: HTMLElement;
+}
+export declare const LANGUAGE_STORAGE_KEY = "language";
+interface I18nState {
+    instance: I18n;
+    languages: readonly LanguageOption[];
+}
+declare global {
+    var mfeflowI18n: I18nState | undefined;
+}
+/** Stored choice, then the first browser language we support (exact or base), then the default. */
+export declare function detectLanguage(supported: readonly string[], stored: string | undefined, preferred: readonly string[], fallback: string): string;
+/**
+ * Creates the page's single i18next instance. Call once, in the shell, before
+ * rendering. Calling it again returns the existing instance.
+ */
+export declare function initI18n(options: InitI18nOptions): Promise<I18n>;
+/** The page's i18next instance. Throws if the shell has not called `initI18n`. */
+export declare function getI18n(): I18n;
+/** Languages the shell configured. */
+export declare function getLanguages(): readonly LanguageOption[];
+export type Messages = Readonly<Record<string, unknown>>;
+/** Usually `(lng) => import(`./i18n/${lng}.json`)`, so messages ship with the remote's own deploy. */
+export type NamespaceLoader = (language: string) => Promise<unknown>;
+/**
+ * Adds a remote's namespace for `language` if it is not loaded yet. If that
+ * language fails to load, the fallback language is loaded instead so the
+ * remote still renders text.
+ */
+export declare function loadNamespace(instance: I18n, namespace: string, loader: NamespaceLoader, language?: string): Promise<void>;
+/** Only for tests: forget the page's instance. */
+export declare function resetI18nForTests(): void;

package/dist/index.js

@@ -0,0 +1,86 @@
+import { createInstance } from "i18next";
+import { initReactI18next } from "react-i18next";
+import { createStorage } from "@mfeflow/storage";
+const LANGUAGE_STORAGE_KEY = 'language';
+function detectLanguage(supported, stored, preferred, fallback) {
+    if (void 0 !== stored && supported.includes(stored)) return stored;
+    for (const lang of preferred){
+        if (supported.includes(lang)) return lang;
+        const base = lang.split('-')[0];
+        if (void 0 !== base && supported.includes(base)) return base;
+    }
+    return fallback;
+}
+function browserLanguages() {
+    return "u" < typeof navigator ? [] : navigator.languages;
+}
+function applyDocumentLanguage(instance, root, lng) {
+    const el = root ?? ("u" < typeof document ? void 0 : document.documentElement);
+    if (!el) return;
+    el.lang = lng;
+    el.dir = instance.dir(lng);
+}
+async function initI18n(options) {
+    if (globalThis.mfeflowI18n) return globalThis.mfeflowI18n.instance;
+    const codes = options.languages.map((l)=>l.code);
+    if (!codes.includes(options.defaultLanguage)) throw new Error(`Default language "${options.defaultLanguage}" is not in the language list`);
+    const storage = options.storage ?? createStorage('shell');
+    const stored = storage.get(LANGUAGE_STORAGE_KEY, void 0, (v)=>'string' == typeof v);
+    const lng = detectLanguage(codes, stored, false === options.detect ? [] : browserLanguages(), options.defaultLanguage);
+    const instance = createInstance();
+    await instance.use(initReactI18next).init({
+        lng,
+        fallbackLng: options.defaultLanguage,
+        supportedLngs: codes,
+        resources: options.resources ?? {},
+        partialBundledLanguages: true,
+        interpolation: {
+            escapeValue: false
+        },
+        react: {
+            useSuspense: false
+        }
+    });
+    applyDocumentLanguage(instance, options.root, lng);
+    instance.on('languageChanged', (next)=>{
+        applyDocumentLanguage(instance, options.root, next);
+        storage.set(LANGUAGE_STORAGE_KEY, next);
+    });
+    globalThis.mfeflowI18n = {
+        instance,
+        languages: options.languages
+    };
+    return instance;
+}
+function getI18n() {
+    const state = globalThis.mfeflowI18n;
+    if (!state) throw new Error('getI18n: the shell must call initI18n() before remotes use translations');
+    return state.instance;
+}
+function getLanguages() {
+    return globalThis.mfeflowI18n?.languages ?? [];
+}
+function isMessages(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+function unwrap(mod) {
+    if (isMessages(mod) && 'default' in mod && isMessages(mod.default)) return mod.default;
+    if (isMessages(mod)) return mod;
+    throw new Error('loadNamespace: the loader must resolve to an object of messages');
+}
+async function loadNamespace(instance, namespace, loader, language = instance.language) {
+    if (instance.hasResourceBundle(language, namespace)) return;
+    try {
+        instance.addResourceBundle(language, namespace, unwrap(await loader(language)), true, false);
+    } catch (error) {
+        const configured = instance.options.fallbackLng;
+        const first = Array.isArray(configured) ? configured[0] : configured;
+        const fallback = 'string' == typeof first ? first : void 0;
+        if (void 0 === fallback || fallback === language || instance.hasResourceBundle(fallback, namespace)) throw error;
+        instance.addResourceBundle(fallback, namespace, unwrap(await loader(fallback)), true, false);
+    }
+}
+function resetI18nForTests() {
+    globalThis.mfeflowI18n = void 0;
+}
+export { LANGUAGE_STORAGE_KEY, detectLanguage, getI18n, getLanguages, initI18n, loadNamespace, resetI18nForTests };

package/dist/react.d.ts

@@ -0,0 +1,20 @@
+import type { TFunction } from 'i18next';
+import { type LanguageOption, type NamespaceLoader } from './index.js';
+export interface MfeTranslation {
+    t: TFunction;
+    /** False until the namespace for the current language has loaded. */
+    ready: boolean;
+    language: string;
+}
+/**
+ * Translations for one remote. Loads `namespace` with `loader` for the current
+ * language when the component mounts, and again whenever the language changes.
+ */
+export declare function useMfeTranslation(namespace: string, loader: NamespaceLoader): MfeTranslation;
+export interface LanguageState {
+    language: string;
+    languages: readonly LanguageOption[];
+    setLanguage: (code: string) => Promise<void>;
+}
+/** The current language, the configured list, and a setter, for language pickers. */
+export declare function useLanguage(): LanguageState;

package/dist/react.js

@@ -0,0 +1,64 @@
+import { useCallback, useEffect, useEffectEvent, useState, useSyncExternalStore } from "react";
+import { useTranslation } from "react-i18next";
+import { getI18n, getLanguages, loadNamespace } from "./index.js";
+function useMfeTranslation(namespace, loader) {
+    const i18n = getI18n();
+    const { t } = useTranslation(namespace, {
+        i18n,
+        useSuspense: false
+    });
+    const loadWith = useEffectEvent((lng)=>loadNamespace(i18n, namespace, loader, lng));
+    const [ready, setReady] = useState(()=>i18n.hasResourceBundle(i18n.language, namespace));
+    const [language, setLanguage] = useState(i18n.language);
+    useEffect(()=>{
+        let alive = true;
+        const load = (lng)=>{
+            setLanguage(lng);
+            setReady(i18n.hasResourceBundle(lng, namespace));
+            loadWith(lng).then(()=>{
+                if (alive) setReady(true);
+            }, (error)=>{
+                console.error(`[mfeflow/i18n] could not load namespace "${namespace}"`, error);
+                if (alive) setReady(true);
+            });
+        };
+        load(i18n.language);
+        i18n.on('languageChanged', load);
+        return ()=>{
+            alive = false;
+            i18n.off('languageChanged', load);
+        };
+    }, [
+        i18n,
+        namespace
+    ]);
+    return {
+        t,
+        ready,
+        language
+    };
+}
+function useLanguage() {
+    const i18n = getI18n();
+    const subscribe = useCallback((onChange)=>{
+        i18n.on('languageChanged', onChange);
+        return ()=>{
+            i18n.off('languageChanged', onChange);
+        };
+    }, [
+        i18n
+    ]);
+    const language = useSyncExternalStore(subscribe, ()=>i18n.language, ()=>i18n.language);
+    const setLanguage = useCallback(async (code)=>{
+        if (!getLanguages().some((l)=>l.code === code)) throw new Error(`Unknown language "${code}"`);
+        await i18n.changeLanguage(code);
+    }, [
+        i18n
+    ]);
+    return {
+        language,
+        languages: getLanguages(),
+        setLanguage
+    };
+}
+export { useLanguage, useMfeTranslation };

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@mfeflow/i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "i18n for micro-frontends: one i18next instance owned by the shell, each remote lazy-loads its own namespace from its own deploy, RTL and persisted language.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "i18n",
+    "i18next",
+    "react-i18next",
+    "rtl",
+    "react",
+    "rsbuild"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/i18n"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mfeflow/storage": "0.1.0"
+  },
+  "peerDependencies": {
+    "i18next": "^26.0.0",
+    "react-i18next": "^17.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@rsbuild/plugin-react": "2.1.1",
+    "@rslib/core": "1.0.5",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "i18next": "26.5.12",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "react-i18next": "17.1.9",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "singleton"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }