react-intl-locale-chain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 i18nagent.ai
+
+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

@@ -0,0 +1,295 @@
+# react-intl-locale-chain
+
+[![npm version](https://img.shields.io/npm/v/react-intl-locale-chain)](https://www.npmjs.com/package/react-intl-locale-chain)
+[![license](https://img.shields.io/npm/l/react-intl-locale-chain)](LICENSE)
+
+Smart locale fallback chains for react-intl — because pt-BR users deserve pt-PT, not English.
+
+## The Problem
+
+react-intl falls back directly to `defaultMessage` or the message ID when a translation key is missing. There is no intermediate locale fallback.
+
+**Example:** Your app has `pt-PT` translations but no `pt-BR` messages file. A Brazilian Portuguese user sees English (or raw message IDs) instead of the perfectly good `pt-PT` translations.
+
+The same thing happens with `es-MX` -> `es`, `fr-CA` -> `fr`, `de-AT` -> `de`, and every other regional variant.
+
+Your users see English when a perfectly good translation exists in a sibling locale.
+
+## The Solution
+
+Drop-in replacement for `IntlProvider`. Zero changes to your existing react-intl components.
+
+`LocaleChainProvider` wraps `IntlProvider` and automatically deep-merges messages from a configurable fallback chain before passing them to react-intl.
+
+## Installation
+
+```bash
+npm install react-intl-locale-chain
+# or
+pnpm add react-intl-locale-chain
+# or
+yarn add react-intl-locale-chain
+```
+
+**Peer dependencies:** `react >= 16.8` and `react-intl >= 5.0.0`
+
+## Quick Start
+
+```tsx
+import { LocaleChainProvider } from 'react-intl-locale-chain';
+
+function App() {
+  return (
+    <LocaleChainProvider
+      locale="pt-BR"
+      defaultLocale="en"
+      loadMessages={(locale) => import(`./messages/${locale}.json`).then(m => m.default)}
+      fallback={<div>Loading...</div>}
+    >
+      <YourApp />
+    </LocaleChainProvider>
+  );
+}
+```
+
+All default fallback chains are active. A `pt-BR` user will now see `pt-PT` translations when `pt-BR` keys are missing.
+
+## Custom Configuration
+
+### Default (zero config)
+
+```tsx
+<LocaleChainProvider
+  locale="pt-BR"
+  defaultLocale="en"
+  loadMessages={loadMessages}
+/>
+```
+
+Uses all built-in fallback chains. Covers Portuguese, Spanish, French, German, Italian, Dutch, Norwegian, and Malay regional variants.
+
+### With overrides (merge with defaults)
+
+```tsx
+// Override specific chains while keeping all defaults
+<LocaleChainProvider
+  locale="pt-BR"
+  defaultLocale="en"
+  loadMessages={loadMessages}
+  overrides={{ 'pt-BR': ['pt'] }}  // skip pt-PT, go straight to pt
+/>
+```
+
+Your overrides replace matching keys in the default map. All other defaults remain.
+
+### Full custom (replace defaults)
+
+```tsx
+// Full control — only use your chains
+<LocaleChainProvider
+  locale="pt-BR"
+  defaultLocale="en"
+  loadMessages={loadMessages}
+  fallbacks={{
+    'pt-BR': ['pt-PT', 'pt'],
+    'es-MX': ['es-419', 'es']
+  }}
+  mergeDefaults={false}
+/>
+```
+
+Only the chains you specify will be active. No defaults.
+
+## Advanced: Pure Utility
+
+For advanced setups where you manage your own `IntlProvider`, use the pure merge function:
+
+```tsx
+import { mergeMessagesFromChain } from 'react-intl-locale-chain';
+import { IntlProvider } from 'react-intl';
+
+// In your setup code (works in Server Components too)
+const messages = await mergeMessagesFromChain({
+  locale: 'pt-BR',
+  defaultLocale: 'en',
+  loadMessages: (locale) => fetch(`/api/messages/${locale}`).then(r => r.json()),
+});
+
+// Pass merged messages to vanilla IntlProvider
+<IntlProvider locale="pt-BR" messages={messages}>
+  <App />
+</IntlProvider>
+```
+
+## Default Fallback Map
+
+### Portuguese
+
+| Locale | Fallback Chain |
+|--------|---------------|
+| pt-BR | pt-PT -> pt -> (default locale) |
+| pt-PT | pt -> (default locale) |
+
+### Spanish
+
+| Locale | Fallback Chain |
+|--------|---------------|
+| es-419 | es -> (default locale) |
+| es-MX | es-419 -> es -> (default locale) |
+| es-AR | es-419 -> es -> (default locale) |
+| es-CO | es-419 -> es -> (default locale) |
+| es-CL | es-419 -> es -> (default locale) |
+| es-PE | es-419 -> es -> (default locale) |
+| es-VE | es-419 -> es -> (default locale) |
+| es-EC | es-419 -> es -> (default locale) |
+| es-GT | es-419 -> es -> (default locale) |
+| es-CU | es-419 -> es -> (default locale) |
+| es-BO | es-419 -> es -> (default locale) |
+| es-DO | es-419 -> es -> (default locale) |
+| es-HN | es-419 -> es -> (default locale) |
+| es-PY | es-419 -> es -> (default locale) |
+| es-SV | es-419 -> es -> (default locale) |
+| es-NI | es-419 -> es -> (default locale) |
+| es-CR | es-419 -> es -> (default locale) |
+| es-PA | es-419 -> es -> (default locale) |
+| es-UY | es-419 -> es -> (default locale) |
+| es-PR | es-419 -> es -> (default locale) |
+
+### French
+
+| Locale | Fallback Chain |
+|--------|---------------|
+| fr-CA | fr -> (default locale) |
+| fr-BE | fr -> (default locale) |
+| fr-CH | fr -> (default locale) |
+| fr-LU | fr -> (default locale) |
+| fr-MC | fr -> (default locale) |
+| fr-SN | fr -> (default locale) |
+| fr-CI | fr -> (default locale) |
+| fr-ML | fr -> (default locale) |
+| fr-CM | fr -> (default locale) |
+| fr-MG | fr -> (default locale) |
+| fr-CD | fr -> (default locale) |
+
+### German
+
+| Locale | Fallback Chain |
+|--------|---------------|
+| de-AT | de -> (default locale) |
+| de-CH | de -> (default locale) |
+| de-LU | de -> (default locale) |
+| de-LI | de -> (default locale) |
+
+### Italian
+
+| Locale | Fallback Chain |
+|--------|---------------|
+| it-CH | it -> (default locale) |
+
+### Dutch
+
+| Locale | Fallback Chain |
+|--------|---------------|
+| nl-BE | nl -> (default locale) |
+
+### Norwegian
+
+| Locale | Fallback Chain |
+|--------|---------------|
+| nb | no -> (default locale) |
+| nn | nb -> no -> (default locale) |
+
+### Malay
+
+| Locale | Fallback Chain |
+|--------|---------------|
+| ms-MY | ms -> (default locale) |
+| ms-SG | ms -> (default locale) |
+| ms-BN | ms -> (default locale) |
+
+## How It Works
+
+1. `LocaleChainProvider` wraps react-intl's `IntlProvider`.
+2. When rendered, it resolves the fallback chain for the requested locale.
+3. It calls your `loadMessages` function for each locale in the chain (in parallel for async loaders).
+4. Messages are deep-merged in priority order: default locale (base) -> chain locales -> requested locale (highest priority).
+5. If `loadMessages` throws for any chain locale (e.g., file doesn't exist), it silently skips that locale and continues.
+6. The merged messages are passed to `IntlProvider`, which sees a complete message object with no missing keys.
+
+## FAQ
+
+**Performance impact?**
+Minimal. The fallback map is resolved once via `useMemo`. Message loading for async loaders happens in parallel (`Promise.allSettled`). Deep merge is fast for typical message objects.
+
+**Does it work with nested message keys?**
+Yes. Deep merge is recursive — it walks all nesting levels. If `pt-BR` has `common.save` but not `common.cancel`, `common.cancel` will be filled from the next locale in the chain.
+
+**What if my `loadMessages` is synchronous?**
+Fully supported. If `loadMessages` returns plain objects (not Promises), `LocaleChainProvider` renders immediately with no loading flash. The sync path is detected automatically.
+
+**What if my `loadMessages` is async?**
+Also fully supported. `LocaleChainProvider` shows the `fallback` prop (or `null`) until messages resolve. Dynamic `import()`, `fetch()` — all work.
+
+**Can I load messages from a CMS or API?**
+Yes. `loadMessages` is just a function — it can load from anywhere:
+
+```tsx
+<LocaleChainProvider
+  locale="pt-BR"
+  defaultLocale="en"
+  loadMessages={async (locale) => {
+    const res = await fetch(`https://my-cms.com/messages/${locale}`)
+    return res.json()
+  }}
+/>
+```
+
+**What if a chain locale doesn't have a messages file?**
+It's silently skipped. The chain continues to the next locale. This is by design — you don't need message files for every locale in every chain.
+
+**react-intl version compatibility?**
+Works with react-intl v5+ and v6+.
+
+**React 19 / Server Components?**
+`LocaleChainProvider` uses `useState` and `useEffect`, so it's a client component. For Server Component architectures, use `mergeMessagesFromChain()` in a Server Component and pass the result to vanilla `IntlProvider`.
+
+**Should `loadMessages` be a stable reference?**
+Yes. Like any function prop in React, define it outside the component or wrap in `useCallback` to avoid unnecessary re-resolution:
+
+```tsx
+// Good — stable reference
+const loadMessages = (locale: string) =>
+  import(`./messages/${locale}.json`).then(m => m.default);
+
+function App() {
+  return (
+    <LocaleChainProvider loadMessages={loadMessages} ... />
+  );
+}
+```
+
+**Should `fallbacks` and `overrides` props be stable references?**
+Yes, like any object prop in React. Define them outside the component or wrap in `useMemo` to avoid unnecessary re-resolution:
+
+```tsx
+// Good — stable reference
+const myOverrides = { 'pt-BR': ['pt'] };
+
+function App() {
+  return (
+    <LocaleChainProvider overrides={myOverrides} ... />
+  );
+}
+```
+
+## Contributing
+
+- Open issues for bugs or feature requests.
+- PRs welcome, especially for adding new locale fallback chains.
+- Run `npm test` before submitting.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+Built by [i18nagent.ai](https://i18nagent.ai)

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { IntlConfig } from 'react-intl';
+
+type Messages = Record<string, any>;
+type FallbackMap = Record<string, string[]>;
+type LoadMessages = (locale: string) => Messages | Promise<Messages>;
+interface LocaleChainConfig {
+    locale: string;
+    defaultLocale: string;
+    loadMessages: LoadMessages;
+    overrides?: FallbackMap;
+    fallbacks?: FallbackMap;
+    mergeDefaults?: boolean;
+}
+/**
+ * Derive IntlProvider props from react-intl's own types for forward compatibility.
+ * We control locale, messages, and defaultLocale — pass everything else through.
+ */
+type IntlProviderPassthroughProps = Omit<Partial<IntlConfig>, 'locale' | 'messages' | 'defaultLocale'>;
+interface LocaleChainProviderProps extends LocaleChainConfig, IntlProviderPassthroughProps {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+}
+
+declare function LocaleChainProvider({ locale, defaultLocale, loadMessages, overrides, fallbacks: fallbacksProp, mergeDefaults: mergeDefaultsProp, children, fallback, ...intlProviderProps }: LocaleChainProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function deepMerge(target: Messages, source: Messages): Messages;
+/**
+ * Resolve effective fallback map from config, then resolve messages.
+ * Pure utility — no React dependency.
+ */
+declare function mergeMessagesFromChain(config: LocaleChainConfig): Promise<Messages>;
+
+declare const defaultFallbacks: FallbackMap;
+declare function mergeFallbacks(defaults: FallbackMap, overrides: FallbackMap): FallbackMap;
+
+export { type FallbackMap, type IntlProviderPassthroughProps, type LoadMessages, type LocaleChainConfig, LocaleChainProvider, type LocaleChainProviderProps, type Messages, deepMerge, defaultFallbacks, mergeFallbacks, mergeMessagesFromChain };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { IntlConfig } from 'react-intl';
+
+type Messages = Record<string, any>;
+type FallbackMap = Record<string, string[]>;
+type LoadMessages = (locale: string) => Messages | Promise<Messages>;
+interface LocaleChainConfig {
+    locale: string;
+    defaultLocale: string;
+    loadMessages: LoadMessages;
+    overrides?: FallbackMap;
+    fallbacks?: FallbackMap;
+    mergeDefaults?: boolean;
+}
+/**
+ * Derive IntlProvider props from react-intl's own types for forward compatibility.
+ * We control locale, messages, and defaultLocale — pass everything else through.
+ */
+type IntlProviderPassthroughProps = Omit<Partial<IntlConfig>, 'locale' | 'messages' | 'defaultLocale'>;
+interface LocaleChainProviderProps extends LocaleChainConfig, IntlProviderPassthroughProps {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+}
+
+declare function LocaleChainProvider({ locale, defaultLocale, loadMessages, overrides, fallbacks: fallbacksProp, mergeDefaults: mergeDefaultsProp, children, fallback, ...intlProviderProps }: LocaleChainProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function deepMerge(target: Messages, source: Messages): Messages;
+/**
+ * Resolve effective fallback map from config, then resolve messages.
+ * Pure utility — no React dependency.
+ */
+declare function mergeMessagesFromChain(config: LocaleChainConfig): Promise<Messages>;
+
+declare const defaultFallbacks: FallbackMap;
+declare function mergeFallbacks(defaults: FallbackMap, overrides: FallbackMap): FallbackMap;
+
+export { type FallbackMap, type IntlProviderPassthroughProps, type LoadMessages, type LocaleChainConfig, LocaleChainProvider, type LocaleChainProviderProps, type Messages, deepMerge, defaultFallbacks, mergeFallbacks, mergeMessagesFromChain };

package/dist/index.js

@@ -0,0 +1,257 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LocaleChainProvider: () => LocaleChainProvider,
+  deepMerge: () => deepMerge,
+  defaultFallbacks: () => defaultFallbacks,
+  mergeFallbacks: () => mergeFallbacks,
+  mergeMessagesFromChain: () => mergeMessagesFromChain
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/locale-chain-provider.tsx
+var import_react = require("react");
+var import_react_intl = require("react-intl");
+
+// src/fallback-map.ts
+var defaultFallbacks = {
+  // Portuguese
+  "pt-BR": ["pt-PT", "pt"],
+  "pt-PT": ["pt"],
+  // Spanish (Latin America uses es-419 as intermediate)
+  "es-419": ["es"],
+  "es-MX": ["es-419", "es"],
+  "es-AR": ["es-419", "es"],
+  "es-CO": ["es-419", "es"],
+  "es-CL": ["es-419", "es"],
+  "es-PE": ["es-419", "es"],
+  "es-VE": ["es-419", "es"],
+  "es-EC": ["es-419", "es"],
+  "es-GT": ["es-419", "es"],
+  "es-CU": ["es-419", "es"],
+  "es-BO": ["es-419", "es"],
+  "es-DO": ["es-419", "es"],
+  "es-HN": ["es-419", "es"],
+  "es-PY": ["es-419", "es"],
+  "es-SV": ["es-419", "es"],
+  "es-NI": ["es-419", "es"],
+  "es-CR": ["es-419", "es"],
+  "es-PA": ["es-419", "es"],
+  "es-UY": ["es-419", "es"],
+  "es-PR": ["es-419", "es"],
+  // French
+  "fr-CA": ["fr"],
+  "fr-BE": ["fr"],
+  "fr-CH": ["fr"],
+  "fr-LU": ["fr"],
+  "fr-MC": ["fr"],
+  "fr-SN": ["fr"],
+  "fr-CI": ["fr"],
+  "fr-ML": ["fr"],
+  "fr-CM": ["fr"],
+  "fr-MG": ["fr"],
+  "fr-CD": ["fr"],
+  // German
+  "de-AT": ["de"],
+  "de-CH": ["de"],
+  "de-LU": ["de"],
+  "de-LI": ["de"],
+  // Italian
+  "it-CH": ["it"],
+  // Dutch
+  "nl-BE": ["nl"],
+  // Norwegian
+  nb: ["no"],
+  nn: ["nb", "no"],
+  // Malay
+  "ms-MY": ["ms"],
+  "ms-SG": ["ms"],
+  "ms-BN": ["ms"]
+};
+function mergeFallbacks(defaults, overrides) {
+  return { ...defaults, ...overrides };
+}
+
+// src/message-resolver.ts
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (source[key] !== null && typeof source[key] === "object" && !Array.isArray(source[key]) && target[key] !== null && typeof target[key] === "object" && !Array.isArray(target[key])) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+function buildLoadOrder({
+  locale,
+  chain,
+  defaultLocale
+}) {
+  const seen = /* @__PURE__ */ new Set();
+  const loadOrder = [];
+  for (const l of [defaultLocale, ...chain.slice().reverse(), locale]) {
+    if (!seen.has(l)) {
+      seen.add(l);
+      loadOrder.push(l);
+    }
+  }
+  return loadOrder;
+}
+async function resolveMessages(opts) {
+  const loadOrder = buildLoadOrder(opts);
+  const results = await Promise.allSettled(
+    loadOrder.map(async (l) => opts.loadMessages(l))
+  );
+  let merged = {};
+  for (const result of results) {
+    if (result.status === "fulfilled") {
+      merged = deepMerge(merged, result.value);
+    }
+  }
+  return merged;
+}
+function resolveMessagesSync(opts) {
+  const loadOrder = buildLoadOrder(opts);
+  let result = {};
+  for (const l of loadOrder) {
+    try {
+      const messages = opts.loadMessages(l);
+      if (messages && typeof messages.then === "function") {
+        return null;
+      }
+      result = deepMerge(result, messages);
+    } catch {
+    }
+  }
+  return result;
+}
+async function mergeMessagesFromChain(config) {
+  const { locale, defaultLocale, loadMessages } = config;
+  let effectiveFallbacks;
+  if (config.fallbacks) {
+    effectiveFallbacks = config.mergeDefaults === false ? config.fallbacks : mergeFallbacks(defaultFallbacks, config.fallbacks);
+  } else if (config.overrides) {
+    effectiveFallbacks = mergeFallbacks(defaultFallbacks, config.overrides);
+  } else {
+    effectiveFallbacks = defaultFallbacks;
+  }
+  const chain = effectiveFallbacks[locale] || [];
+  return resolveMessages({ locale, chain, defaultLocale, loadMessages });
+}
+
+// src/locale-chain-provider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function LocaleChainProvider({
+  locale,
+  defaultLocale,
+  loadMessages,
+  overrides,
+  fallbacks: fallbacksProp,
+  mergeDefaults: mergeDefaultsProp,
+  children,
+  fallback = null,
+  ...intlProviderProps
+}) {
+  const effectiveFallbacks = (0, import_react.useMemo)(() => {
+    if (fallbacksProp) {
+      return mergeDefaultsProp === false ? fallbacksProp : mergeFallbacks(defaultFallbacks, fallbacksProp);
+    }
+    if (overrides) {
+      return mergeFallbacks(defaultFallbacks, overrides);
+    }
+    return defaultFallbacks;
+  }, [fallbacksProp, overrides, mergeDefaultsProp]);
+  const chain = (0, import_react.useMemo)(
+    () => effectiveFallbacks[locale] || [],
+    [effectiveFallbacks, locale]
+  );
+  const [state, setState] = (0, import_react.useState)(() => {
+    try {
+      const result = resolveMessagesSync({
+        locale,
+        chain,
+        defaultLocale,
+        loadMessages
+      });
+      if (result !== null) {
+        return { messages: result, loading: false, resolvedLocale: locale };
+      }
+    } catch {
+    }
+    return { messages: null, loading: true, resolvedLocale: null };
+  });
+  (0, import_react.useEffect)(() => {
+    try {
+      const syncResult = resolveMessagesSync({
+        locale,
+        chain,
+        defaultLocale,
+        loadMessages
+      });
+      if (syncResult !== null) {
+        setState({ messages: syncResult, loading: false, resolvedLocale: locale });
+        return;
+      }
+    } catch {
+    }
+    let cancelled = false;
+    setState((prev) => ({ ...prev, loading: true }));
+    resolveMessages({ locale, chain, defaultLocale, loadMessages }).then(
+      (merged) => {
+        if (!cancelled) {
+          setState({ messages: merged, loading: false, resolvedLocale: locale });
+        }
+      },
+      () => {
+        if (!cancelled) {
+          setState({ messages: {}, loading: false, resolvedLocale: locale });
+        }
+      }
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [locale, defaultLocale, loadMessages, chain]);
+  if (state.loading || state.messages === null) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: fallback });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    import_react_intl.IntlProvider,
+    {
+      locale,
+      messages: state.messages,
+      defaultLocale,
+      ...intlProviderProps,
+      children
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LocaleChainProvider,
+  deepMerge,
+  defaultFallbacks,
+  mergeFallbacks,
+  mergeMessagesFromChain
+});

package/dist/index.mjs

@@ -0,0 +1,226 @@
+// src/locale-chain-provider.tsx
+import { useState, useEffect, useMemo } from "react";
+import { IntlProvider } from "react-intl";
+
+// src/fallback-map.ts
+var defaultFallbacks = {
+  // Portuguese
+  "pt-BR": ["pt-PT", "pt"],
+  "pt-PT": ["pt"],
+  // Spanish (Latin America uses es-419 as intermediate)
+  "es-419": ["es"],
+  "es-MX": ["es-419", "es"],
+  "es-AR": ["es-419", "es"],
+  "es-CO": ["es-419", "es"],
+  "es-CL": ["es-419", "es"],
+  "es-PE": ["es-419", "es"],
+  "es-VE": ["es-419", "es"],
+  "es-EC": ["es-419", "es"],
+  "es-GT": ["es-419", "es"],
+  "es-CU": ["es-419", "es"],
+  "es-BO": ["es-419", "es"],
+  "es-DO": ["es-419", "es"],
+  "es-HN": ["es-419", "es"],
+  "es-PY": ["es-419", "es"],
+  "es-SV": ["es-419", "es"],
+  "es-NI": ["es-419", "es"],
+  "es-CR": ["es-419", "es"],
+  "es-PA": ["es-419", "es"],
+  "es-UY": ["es-419", "es"],
+  "es-PR": ["es-419", "es"],
+  // French
+  "fr-CA": ["fr"],
+  "fr-BE": ["fr"],
+  "fr-CH": ["fr"],
+  "fr-LU": ["fr"],
+  "fr-MC": ["fr"],
+  "fr-SN": ["fr"],
+  "fr-CI": ["fr"],
+  "fr-ML": ["fr"],
+  "fr-CM": ["fr"],
+  "fr-MG": ["fr"],
+  "fr-CD": ["fr"],
+  // German
+  "de-AT": ["de"],
+  "de-CH": ["de"],
+  "de-LU": ["de"],
+  "de-LI": ["de"],
+  // Italian
+  "it-CH": ["it"],
+  // Dutch
+  "nl-BE": ["nl"],
+  // Norwegian
+  nb: ["no"],
+  nn: ["nb", "no"],
+  // Malay
+  "ms-MY": ["ms"],
+  "ms-SG": ["ms"],
+  "ms-BN": ["ms"]
+};
+function mergeFallbacks(defaults, overrides) {
+  return { ...defaults, ...overrides };
+}
+
+// src/message-resolver.ts
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (source[key] !== null && typeof source[key] === "object" && !Array.isArray(source[key]) && target[key] !== null && typeof target[key] === "object" && !Array.isArray(target[key])) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+function buildLoadOrder({
+  locale,
+  chain,
+  defaultLocale
+}) {
+  const seen = /* @__PURE__ */ new Set();
+  const loadOrder = [];
+  for (const l of [defaultLocale, ...chain.slice().reverse(), locale]) {
+    if (!seen.has(l)) {
+      seen.add(l);
+      loadOrder.push(l);
+    }
+  }
+  return loadOrder;
+}
+async function resolveMessages(opts) {
+  const loadOrder = buildLoadOrder(opts);
+  const results = await Promise.allSettled(
+    loadOrder.map(async (l) => opts.loadMessages(l))
+  );
+  let merged = {};
+  for (const result of results) {
+    if (result.status === "fulfilled") {
+      merged = deepMerge(merged, result.value);
+    }
+  }
+  return merged;
+}
+function resolveMessagesSync(opts) {
+  const loadOrder = buildLoadOrder(opts);
+  let result = {};
+  for (const l of loadOrder) {
+    try {
+      const messages = opts.loadMessages(l);
+      if (messages && typeof messages.then === "function") {
+        return null;
+      }
+      result = deepMerge(result, messages);
+    } catch {
+    }
+  }
+  return result;
+}
+async function mergeMessagesFromChain(config) {
+  const { locale, defaultLocale, loadMessages } = config;
+  let effectiveFallbacks;
+  if (config.fallbacks) {
+    effectiveFallbacks = config.mergeDefaults === false ? config.fallbacks : mergeFallbacks(defaultFallbacks, config.fallbacks);
+  } else if (config.overrides) {
+    effectiveFallbacks = mergeFallbacks(defaultFallbacks, config.overrides);
+  } else {
+    effectiveFallbacks = defaultFallbacks;
+  }
+  const chain = effectiveFallbacks[locale] || [];
+  return resolveMessages({ locale, chain, defaultLocale, loadMessages });
+}
+
+// src/locale-chain-provider.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+function LocaleChainProvider({
+  locale,
+  defaultLocale,
+  loadMessages,
+  overrides,
+  fallbacks: fallbacksProp,
+  mergeDefaults: mergeDefaultsProp,
+  children,
+  fallback = null,
+  ...intlProviderProps
+}) {
+  const effectiveFallbacks = useMemo(() => {
+    if (fallbacksProp) {
+      return mergeDefaultsProp === false ? fallbacksProp : mergeFallbacks(defaultFallbacks, fallbacksProp);
+    }
+    if (overrides) {
+      return mergeFallbacks(defaultFallbacks, overrides);
+    }
+    return defaultFallbacks;
+  }, [fallbacksProp, overrides, mergeDefaultsProp]);
+  const chain = useMemo(
+    () => effectiveFallbacks[locale] || [],
+    [effectiveFallbacks, locale]
+  );
+  const [state, setState] = useState(() => {
+    try {
+      const result = resolveMessagesSync({
+        locale,
+        chain,
+        defaultLocale,
+        loadMessages
+      });
+      if (result !== null) {
+        return { messages: result, loading: false, resolvedLocale: locale };
+      }
+    } catch {
+    }
+    return { messages: null, loading: true, resolvedLocale: null };
+  });
+  useEffect(() => {
+    try {
+      const syncResult = resolveMessagesSync({
+        locale,
+        chain,
+        defaultLocale,
+        loadMessages
+      });
+      if (syncResult !== null) {
+        setState({ messages: syncResult, loading: false, resolvedLocale: locale });
+        return;
+      }
+    } catch {
+    }
+    let cancelled = false;
+    setState((prev) => ({ ...prev, loading: true }));
+    resolveMessages({ locale, chain, defaultLocale, loadMessages }).then(
+      (merged) => {
+        if (!cancelled) {
+          setState({ messages: merged, loading: false, resolvedLocale: locale });
+        }
+      },
+      () => {
+        if (!cancelled) {
+          setState({ messages: {}, loading: false, resolvedLocale: locale });
+        }
+      }
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [locale, defaultLocale, loadMessages, chain]);
+  if (state.loading || state.messages === null) {
+    return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+  }
+  return /* @__PURE__ */ jsx(
+    IntlProvider,
+    {
+      locale,
+      messages: state.messages,
+      defaultLocale,
+      ...intlProviderProps,
+      children
+    }
+  );
+}
+export {
+  LocaleChainProvider,
+  deepMerge,
+  defaultFallbacks,
+  mergeFallbacks,
+  mergeMessagesFromChain
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "react-intl-locale-chain",
+  "version": "0.1.0",
+  "description": "Smart locale fallback chains for react-intl",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-intl": ">=5.0.0"
+  },
+  "devDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "react-intl": "^6.0.0",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/jest-dom": "^6.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "tsup": "^8.0.0",
+    "@types/react": "^18.0.0",
+    "jsdom": "^24.0.0"
+  },
+  "keywords": [
+    "react-intl",
+    "formatjs",
+    "i18n",
+    "locale",
+    "fallback",
+    "chain",
+    "localization",
+    "internationalization"
+  ],
+  "author": "i18nagent.ai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/i18n-agent/react-intl-localechain"
+  },
+  "homepage": "https://github.com/i18n-agent/react-intl-localechain#readme",
+  "bugs": {
+    "url": "https://github.com/i18n-agent/react-intl-localechain/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  }
+}