localize-react 1.6.0 → 2.0.0-next.0

package/dist/index.d.cts

@@ -0,0 +1,138 @@
+import * as react from 'react';
+import { ReactNode, JSX } from 'react';
+
+/**
+ * A nested translation tree. Leaves are `string` (the localized text);
+ * branches are nested objects keyed by the next segment of a dot-path.
+ *
+ * @example
+ * ```ts
+ * const translations: Translations = {
+ *   en: { greeting: { hello: 'Hi {{name}}!' } },
+ *   fr: { greeting: { hello: 'Salut {{name}} !' } },
+ * };
+ * ```
+ */
+interface Translations {
+    readonly [key: string]: string | Translations;
+}
+/**
+ * Values to interpolate into a translation template. Keys correspond to
+ * `{{placeholder}}` tokens inside the translation string.
+ *
+ * Numbers are coerced to their `String()` form at render time.
+ */
+type TemplateValues = Readonly<Record<string, string | number>>;
+/**
+ * Translate function returned by {@link useLocalize} and exposed on
+ * {@link LocalizationContext}.
+ *
+ * @param descriptor    Translation key. Use dot-notation (`a.b.c`) to
+ *                      walk nested {@link Translations} trees.
+ * @param values        Optional interpolation values for `{{name}}`-style
+ *                      mustaches inside the resolved translation.
+ * @param defaultMessage Fallback used when the descriptor cannot be
+ *                       resolved. If omitted, the descriptor itself is
+ *                       returned (preserving v1 behaviour).
+ * @returns The resolved, interpolated translation string.
+ */
+type Translate = (descriptor: string, values?: TemplateValues, defaultMessage?: string) => string;
+/**
+ * Value carried by {@link LocalizationContext}. Available via
+ * {@link useLocalize}, {@link LocalizationConsumer}, or
+ * `static contextType` in class components.
+ */
+interface LocalizationContextValue {
+    /** Currently active locale, exactly as it was passed to the provider. */
+    readonly locale: string | undefined;
+    /** Translate a descriptor against the active locale. */
+    readonly translate: Translate;
+    /** The full translations tree, unmodified. */
+    readonly translations: Translations;
+}
+/** Props accepted by {@link LocalizationProvider}. */
+interface LocalizationProviderProps {
+    /** Provider subtree. */
+    readonly children?: ReactNode;
+    /**
+     * Locale to look up inside {@link Translations}. If omitted, the
+     * `translations` object is treated as the flat translation map.
+     *
+     * Resolution order: exact match → `lower_case_with_underscores` →
+     * leading segment (`en_us` → `en`). A warning is logged if none match.
+     */
+    readonly locale?: string;
+    /** Translation tree (per-locale or flat). Required. */
+    readonly translations: Translations;
+    /**
+     * Disable the internal LRU-free memo cache. Useful in dev when
+     * mutating translation objects in place. Defaults to `false`.
+     */
+    readonly disableCache?: boolean;
+}
+/** Props accepted by {@link Message}. */
+interface MessageProps {
+    /** Translation key — see {@link Translate}. */
+    readonly descriptor: string;
+    /** Interpolation values for `{{placeholder}}` tokens. */
+    readonly values?: TemplateValues;
+    /** Fallback string when `descriptor` cannot be resolved. */
+    readonly defaultMessage?: string;
+}
+
+/**
+ * React context carrying the active translate function. Prefer
+ * {@link useLocalize} or {@link LocalizationConsumer} in new code;
+ * `static contextType = LocalizationContext` is supported for legacy
+ * class components.
+ */
+declare const LocalizationContext: react.Context<LocalizationContextValue>;
+/**
+ * Provides translation data to descendants. Wrap the root of your app
+ * (or the subtree that needs translations) with this component.
+ *
+ * @example
+ * ```tsx
+ * <LocalizationProvider locale="en" translations={messages}>
+ *   <App />
+ * </LocalizationProvider>
+ * ```
+ */
+declare function LocalizationProvider({ children, disableCache, locale, translations, }: LocalizationProviderProps): JSX.Element;
+/**
+ * Render-prop consumer for {@link LocalizationContext}. Prefer
+ * {@link useLocalize} in function components.
+ */
+declare const LocalizationConsumer: react.Consumer<LocalizationContextValue>;
+
+/**
+ * Read the current {@link LocalizationContextValue} from the nearest
+ * {@link LocalizationProvider}. Throws nothing if there is no provider —
+ * a no-op `translate` (returns the descriptor) is used instead.
+ *
+ * @example
+ * ```tsx
+ * function Greeting() {
+ *   const { translate } = useLocalize();
+ *   return <h1>{translate('greeting.hello', { name: 'World' })}</h1>;
+ * }
+ * ```
+ */
+declare function useLocalize(): LocalizationContextValue;
+
+/**
+ * Render a translated string by descriptor.
+ *
+ * Equivalent to inlining `useLocalize().translate(descriptor, values,
+ * defaultMessage)`. Use this when you want a component instead of a
+ * hook call (e.g. inside `<button title={...} />` is not possible, but
+ * `<button title="..."><Message .../></button>` reads fine in JSX).
+ *
+ * @example
+ * ```tsx
+ * <Message descriptor="greeting.hello" values={{ name: 'Alex' }} />
+ * ```
+ */
+declare function Message({ defaultMessage, descriptor, values, }: MessageProps): string;
+
+export { LocalizationConsumer, LocalizationContext, type LocalizationContextValue, LocalizationProvider, type LocalizationProviderProps, Message, type MessageProps, type TemplateValues, type Translate, type Translations, useLocalize };

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import * as react from 'react';
+import { ReactNode, JSX } from 'react';
+
+/**
+ * A nested translation tree. Leaves are `string` (the localized text);
+ * branches are nested objects keyed by the next segment of a dot-path.
+ *
+ * @example
+ * ```ts
+ * const translations: Translations = {
+ *   en: { greeting: { hello: 'Hi {{name}}!' } },
+ *   fr: { greeting: { hello: 'Salut {{name}} !' } },
+ * };
+ * ```
+ */
+interface Translations {
+    readonly [key: string]: string | Translations;
+}
+/**
+ * Values to interpolate into a translation template. Keys correspond to
+ * `{{placeholder}}` tokens inside the translation string.
+ *
+ * Numbers are coerced to their `String()` form at render time.
+ */
+type TemplateValues = Readonly<Record<string, string | number>>;
+/**
+ * Translate function returned by {@link useLocalize} and exposed on
+ * {@link LocalizationContext}.
+ *
+ * @param descriptor    Translation key. Use dot-notation (`a.b.c`) to
+ *                      walk nested {@link Translations} trees.
+ * @param values        Optional interpolation values for `{{name}}`-style
+ *                      mustaches inside the resolved translation.
+ * @param defaultMessage Fallback used when the descriptor cannot be
+ *                       resolved. If omitted, the descriptor itself is
+ *                       returned (preserving v1 behaviour).
+ * @returns The resolved, interpolated translation string.
+ */
+type Translate = (descriptor: string, values?: TemplateValues, defaultMessage?: string) => string;
+/**
+ * Value carried by {@link LocalizationContext}. Available via
+ * {@link useLocalize}, {@link LocalizationConsumer}, or
+ * `static contextType` in class components.
+ */
+interface LocalizationContextValue {
+    /** Currently active locale, exactly as it was passed to the provider. */
+    readonly locale: string | undefined;
+    /** Translate a descriptor against the active locale. */
+    readonly translate: Translate;
+    /** The full translations tree, unmodified. */
+    readonly translations: Translations;
+}
+/** Props accepted by {@link LocalizationProvider}. */
+interface LocalizationProviderProps {
+    /** Provider subtree. */
+    readonly children?: ReactNode;
+    /**
+     * Locale to look up inside {@link Translations}. If omitted, the
+     * `translations` object is treated as the flat translation map.
+     *
+     * Resolution order: exact match → `lower_case_with_underscores` →
+     * leading segment (`en_us` → `en`). A warning is logged if none match.
+     */
+    readonly locale?: string;
+    /** Translation tree (per-locale or flat). Required. */
+    readonly translations: Translations;
+    /**
+     * Disable the internal LRU-free memo cache. Useful in dev when
+     * mutating translation objects in place. Defaults to `false`.
+     */
+    readonly disableCache?: boolean;
+}
+/** Props accepted by {@link Message}. */
+interface MessageProps {
+    /** Translation key — see {@link Translate}. */
+    readonly descriptor: string;
+    /** Interpolation values for `{{placeholder}}` tokens. */
+    readonly values?: TemplateValues;
+    /** Fallback string when `descriptor` cannot be resolved. */
+    readonly defaultMessage?: string;
+}
+
+/**
+ * React context carrying the active translate function. Prefer
+ * {@link useLocalize} or {@link LocalizationConsumer} in new code;
+ * `static contextType = LocalizationContext` is supported for legacy
+ * class components.
+ */
+declare const LocalizationContext: react.Context<LocalizationContextValue>;
+/**
+ * Provides translation data to descendants. Wrap the root of your app
+ * (or the subtree that needs translations) with this component.
+ *
+ * @example
+ * ```tsx
+ * <LocalizationProvider locale="en" translations={messages}>
+ *   <App />
+ * </LocalizationProvider>
+ * ```
+ */
+declare function LocalizationProvider({ children, disableCache, locale, translations, }: LocalizationProviderProps): JSX.Element;
+/**
+ * Render-prop consumer for {@link LocalizationContext}. Prefer
+ * {@link useLocalize} in function components.
+ */
+declare const LocalizationConsumer: react.Consumer<LocalizationContextValue>;
+
+/**
+ * Read the current {@link LocalizationContextValue} from the nearest
+ * {@link LocalizationProvider}. Throws nothing if there is no provider —
+ * a no-op `translate` (returns the descriptor) is used instead.
+ *
+ * @example
+ * ```tsx
+ * function Greeting() {
+ *   const { translate } = useLocalize();
+ *   return <h1>{translate('greeting.hello', { name: 'World' })}</h1>;
+ * }
+ * ```
+ */
+declare function useLocalize(): LocalizationContextValue;
+
+/**
+ * Render a translated string by descriptor.
+ *
+ * Equivalent to inlining `useLocalize().translate(descriptor, values,
+ * defaultMessage)`. Use this when you want a component instead of a
+ * hook call (e.g. inside `<button title={...} />` is not possible, but
+ * `<button title="..."><Message .../></button>` reads fine in JSX).
+ *
+ * @example
+ * ```tsx
+ * <Message descriptor="greeting.hello" values={{ name: 'Alex' }} />
+ * ```
+ */
+declare function Message({ defaultMessage, descriptor, values, }: MessageProps): string;
+
+export { LocalizationConsumer, LocalizationContext, type LocalizationContextValue, LocalizationProvider, type LocalizationProviderProps, Message, type MessageProps, type TemplateValues, type Translate, type Translations, useLocalize };

package/dist/index.mjs

@@ -0,0 +1,127 @@
+import { createContext, useMemo, useEffect, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/Provider.tsx
+
+// src/helpers.ts
+var NO_TRANSLATION_WARNING_MESSAGE = "[LOCALIZE-REACT]: There are no translations for specified locale";
+var NO_TEMPLATE_VALUE_MESSAGE = "[LOCALIZE-REACT] Looks like template is being used, but no value passed for ";
+var PARSE_TEMPLATE_REGEXP = /\{\{([^{}]+)\}\}/g;
+var translationCache = /* @__PURE__ */ Object.create(null);
+function sanitizeLocale(locale, translations) {
+  if (!locale) return null;
+  if (typeof translations[locale] === "object") return locale;
+  const normalized = locale.toLowerCase().replaceAll("-", "_");
+  if (typeof translations[normalized] === "object") return normalized;
+  const short = normalized.split("_")[0];
+  if (short && typeof translations[short] === "object") return short;
+  console.warn(NO_TRANSLATION_WARNING_MESSAGE, locale);
+  return locale;
+}
+function memoize(fn) {
+  return (descriptor, values, defaultMessage) => {
+    const cacheKey = values ? JSON.stringify(values) + descriptor + (defaultMessage ?? "") : descriptor + (defaultMessage ?? "");
+    const cached = translationCache[cacheKey];
+    if (cached !== void 0) return cached;
+    const output = fn(descriptor, values, defaultMessage);
+    translationCache[cacheKey] = output;
+    return output;
+  };
+}
+function clearCache() {
+  translationCache = /* @__PURE__ */ Object.create(null);
+}
+function transformToPairs(templates, values) {
+  return templates.map((token) => {
+    const placeholderKey = token.slice(2, -2);
+    if (Object.hasOwn(values, placeholderKey)) {
+      return [token, values[placeholderKey]];
+    }
+    console.warn(NO_TEMPLATE_VALUE_MESSAGE, token);
+    return [token, token];
+  });
+}
+function buildTranslation(source, values) {
+  if (!values) return source;
+  if (Object.keys(values).length === 0) return source;
+  const templates = source.match(PARSE_TEMPLATE_REGEXP);
+  if (!templates || templates.length === 0) return source;
+  const pairs = transformToPairs(templates, values);
+  let result = source;
+  for (const [token, value] of pairs) {
+    result = result.replaceAll(token, String(value));
+  }
+  return result;
+}
+var DEFAULT_CONTEXT_VALUE = {
+  locale: void 0,
+  translate: (descriptor, _values, defaultMessage) => defaultMessage ?? descriptor,
+  translations: {}
+};
+var LocalizationContext = createContext(
+  DEFAULT_CONTEXT_VALUE
+);
+LocalizationContext.displayName = "LocalizationContext";
+function LocalizationProvider({
+  children,
+  disableCache = false,
+  locale,
+  translations = {}
+}) {
+  const pureTranslations = useMemo(() => {
+    const sanitizedLocale = sanitizeLocale(locale, translations);
+    const localeTranslations = sanitizedLocale === null ? translations : translations[sanitizedLocale];
+    return localeTranslations && typeof localeTranslations === "object" ? localeTranslations : {};
+  }, [locale, translations]);
+  useEffect(() => {
+    clearCache();
+  }, [locale, translations]);
+  const translate = useMemo(() => {
+    const pureTranslate = (descriptor, values, defaultMessage) => {
+      if (!descriptor) return defaultMessage ?? descriptor;
+      const fallback = typeof defaultMessage === "string" ? defaultMessage : descriptor;
+      const direct = pureTranslations[descriptor];
+      if (typeof direct === "string") {
+        return values ? buildTranslation(direct, values) : direct;
+      }
+      const segments = descriptor.split(".");
+      if (segments.length === 1) {
+        return buildTranslation(fallback, values);
+      }
+      const resolved = resolveNestedKey(pureTranslations, segments);
+      return typeof resolved === "string" ? buildTranslation(resolved, values) : buildTranslation(fallback, values);
+    };
+    return disableCache ? pureTranslate : memoize(pureTranslate);
+  }, [disableCache, pureTranslations]);
+  const value = useMemo(
+    () => ({ locale, translate, translations }),
+    [locale, translate, translations]
+  );
+  return /* @__PURE__ */ jsx(LocalizationContext.Provider, { value, children });
+}
+var LocalizationConsumer = LocalizationContext.Consumer;
+function resolveNestedKey(tree, segments) {
+  let cursor = tree;
+  for (const segment of segments) {
+    if (cursor === void 0 || typeof cursor === "string") return void 0;
+    cursor = cursor[segment];
+  }
+  return typeof cursor === "string" ? cursor : void 0;
+}
+function useLocalize() {
+  return useContext(LocalizationContext);
+}
+
+// src/Message.tsx
+function Message({
+  defaultMessage,
+  descriptor,
+  values
+}) {
+  const { translate } = useLocalize();
+  return translate(descriptor, values, defaultMessage);
+}
+
+export { LocalizationConsumer, LocalizationContext, LocalizationProvider, Message, useLocalize };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers.ts","../src/Provider.tsx","../src/use-localize.ts","../src/Message.tsx"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import type { TemplateValues, Translate, Translations } from './types.js';\n\n/** Warning logged when no locale entry matches the requested locale. */\nexport const NO_TRANSLATION_WARNING_MESSAGE =\n  '[LOCALIZE-REACT]: There are no translations for specified locale';\n\n/** Warning logged when a `{{placeholder}}` has no matching value. */\nexport const NO_TEMPLATE_VALUE_MESSAGE =\n  '[LOCALIZE-REACT] Looks like template is being used, but no value passed for ';\n\n/**\n * Pattern matching `{{name}}`-style mustaches. Anchored to avoid\n * consuming adjacent braces (`{{{a}}}` only matches `{{a}}`).\n */\nexport const PARSE_TEMPLATE_REGEXP = /\\{\\{([^{}]+)\\}\\}/g;\n\n/**\n * Module-scoped translation cache. Kept module-scoped (rather than\n * provider-scoped) for behavioural parity with v1.x; see ADR-008.\n */\nlet translationCache: Record<string, string> = Object.create(null) as Record<\n  string,\n  string\n>;\n\n/**\n * Normalize a locale string against the available translation keys.\n *\n * - Returns `null` if no locale was supplied.\n * - Returns the input as-is if `translations[locale]` is an object.\n * - Lowercases and replaces dashes with underscores, then retries.\n * - Falls back to the leading segment (`en_us` → `en`).\n * - If nothing matches, logs a warning and returns the original input.\n */\nexport function sanitizeLocale(\n  locale: string | undefined,\n  translations: Translations,\n): string | null {\n  if (!locale) return null;\n\n  if (typeof translations[locale] === 'object') return locale;\n\n  const normalized = locale.toLowerCase().replaceAll('-', '_');\n  if (typeof translations[normalized] === 'object') return normalized;\n\n  const short = normalized.split('_')[0];\n  if (short && typeof translations[short] === 'object') return short;\n\n  console.warn(NO_TRANSLATION_WARNING_MESSAGE, locale);\n  return locale;\n}\n\n/**\n * Returns a memoizing wrapper around {@link fn}. The cache key combines\n * the descriptor, the JSON-serialized values, and the default message.\n */\nexport function memoize(fn: Translate): Translate {\n  return (descriptor, values, defaultMessage) => {\n    const cacheKey = values\n      ? JSON.stringify(values) + descriptor + (defaultMessage ?? '')\n      : descriptor + (defaultMessage ?? '');\n\n    const cached = translationCache[cacheKey];\n    if (cached !== undefined) return cached;\n\n    const output = fn(descriptor, values, defaultMessage);\n    translationCache[cacheKey] = output;\n    return output;\n  };\n}\n\n/** Reset the module-level translation cache. */\nexport function clearCache(): void {\n  translationCache = Object.create(null) as Record<string, string>;\n}\n\n/**\n * Pair each `{{key}}` template token with the matching value from\n * {@link values}. Tokens with no value are paired with themselves and\n * logged.\n */\nexport function transformToPairs(\n  templates: readonly string[],\n  values: TemplateValues,\n): readonly (readonly [string, string | number])[] {\n  return templates.map((token) => {\n    const placeholderKey = token.slice(2, -2);\n    if (Object.hasOwn(values, placeholderKey)) {\n      return [token, values[placeholderKey]!] as const;\n    }\n    console.warn(NO_TEMPLATE_VALUE_MESSAGE, token);\n    return [token, token] as const;\n  });\n}\n\n/**\n * Replace every `{{placeholder}}` token in {@link source} with its\n * corresponding entry from {@link values}. Uses literal string\n * replacement (not `new RegExp(token)`) so values containing regex\n * meta-characters are safe — see MIGRATION_PLAN.md risk R4.\n */\nexport function buildTranslation(\n  source: string,\n  values?: TemplateValues,\n): string {\n  if (!values) return source;\n  if (Object.keys(values).length === 0) return source;\n\n  const templates = source.match(PARSE_TEMPLATE_REGEXP);\n  if (!templates || templates.length === 0) return source;\n\n  const pairs = transformToPairs(templates, values);\n\n  let result = source;\n  for (const [token, value] of pairs) {\n    result = result.replaceAll(token, String(value));\n  }\n  return result;\n}\n","import { createContext, useEffect, useMemo } from 'react';\nimport type { JSX } from 'react';\n\nimport {\n  buildTranslation,\n  clearCache,\n  memoize,\n  sanitizeLocale,\n} from './helpers.js';\nimport type {\n  LocalizationContextValue,\n  LocalizationProviderProps,\n  TemplateValues,\n  Translate,\n  Translations,\n} from './types.js';\n\nconst DEFAULT_CONTEXT_VALUE: LocalizationContextValue = {\n  locale: undefined,\n  translate: (descriptor, _values, defaultMessage) =>\n    defaultMessage ?? descriptor,\n  translations: {},\n};\n\n/**\n * React context carrying the active translate function. Prefer\n * {@link useLocalize} or {@link LocalizationConsumer} in new code;\n * `static contextType = LocalizationContext` is supported for legacy\n * class components.\n */\nexport const LocalizationContext = createContext<LocalizationContextValue>(\n  DEFAULT_CONTEXT_VALUE,\n);\n\nLocalizationContext.displayName = 'LocalizationContext';\n\n/**\n * Provides translation data to descendants. Wrap the root of your app\n * (or the subtree that needs translations) with this component.\n *\n * @example\n * ```tsx\n * <LocalizationProvider locale=\"en\" translations={messages}>\n *   <App />\n * </LocalizationProvider>\n * ```\n */\nexport function LocalizationProvider({\n  children,\n  disableCache = false,\n  locale,\n  translations = {},\n}: LocalizationProviderProps): JSX.Element {\n  const pureTranslations = useMemo<Translations>(() => {\n    const sanitizedLocale = sanitizeLocale(locale, translations);\n    const localeTranslations: Translations | string | undefined =\n      sanitizedLocale === null ? translations : translations[sanitizedLocale];\n    return localeTranslations && typeof localeTranslations === 'object'\n      ? localeTranslations\n      : {};\n  }, [locale, translations]);\n\n  useEffect(() => {\n    clearCache();\n  }, [locale, translations]);\n\n  const translate = useMemo<Translate>(() => {\n    const pureTranslate: Translate = (descriptor, values, defaultMessage) => {\n      if (!descriptor) return defaultMessage ?? descriptor;\n\n      const fallback =\n        typeof defaultMessage === 'string' ? defaultMessage : descriptor;\n\n      const direct = pureTranslations[descriptor];\n      if (typeof direct === 'string') {\n        return values ? buildTranslation(direct, values) : direct;\n      }\n\n      const segments = descriptor.split('.');\n      if (segments.length === 1) {\n        return buildTranslation(fallback, values);\n      }\n\n      const resolved = resolveNestedKey(pureTranslations, segments);\n      return typeof resolved === 'string'\n        ? buildTranslation(resolved, values)\n        : buildTranslation(fallback, values);\n    };\n\n    return disableCache ? pureTranslate : memoize(pureTranslate);\n  }, [disableCache, pureTranslations]);\n\n  const value = useMemo<LocalizationContextValue>(\n    () => ({ locale, translate, translations }),\n    [locale, translate, translations],\n  );\n\n  return (\n    <LocalizationContext.Provider value={value}>\n      {children}\n    </LocalizationContext.Provider>\n  );\n}\n\n/**\n * Render-prop consumer for {@link LocalizationContext}. Prefer\n * {@link useLocalize} in function components.\n */\nexport const LocalizationConsumer = LocalizationContext.Consumer;\n\nfunction resolveNestedKey(\n  tree: Translations,\n  segments: readonly string[],\n): string | undefined {\n  let cursor: string | Translations | undefined = tree;\n  for (const segment of segments) {\n    if (cursor === undefined || typeof cursor === 'string') return undefined;\n    cursor = cursor[segment];\n  }\n  return typeof cursor === 'string' ? cursor : undefined;\n}\n\n// `TemplateValues` re-export keeps the file self-contained for the\n// snapshot of the public type surface; do not remove without updating\n// `src/index.ts`.\nexport type { TemplateValues };\n","import { useContext } from 'react';\n\nimport { LocalizationContext } from './Provider.js';\nimport type { LocalizationContextValue } from './types.js';\n\n/**\n * Read the current {@link LocalizationContextValue} from the nearest\n * {@link LocalizationProvider}. Throws nothing if there is no provider —\n * a no-op `translate` (returns the descriptor) is used instead.\n *\n * @example\n * ```tsx\n * function Greeting() {\n *   const { translate } = useLocalize();\n *   return <h1>{translate('greeting.hello', { name: 'World' })}</h1>;\n * }\n * ```\n */\nexport function useLocalize(): LocalizationContextValue {\n  return useContext(LocalizationContext);\n}\n","import type { MessageProps } from './types.js';\nimport { useLocalize } from './use-localize.js';\n\n/**\n * Render a translated string by descriptor.\n *\n * Equivalent to inlining `useLocalize().translate(descriptor, values,\n * defaultMessage)`. Use this when you want a component instead of a\n * hook call (e.g. inside `<button title={...} />` is not possible, but\n * `<button title=\"...\"><Message .../></button>` reads fine in JSX).\n *\n * @example\n * ```tsx\n * <Message descriptor=\"greeting.hello\" values={{ name: 'Alex' }} />\n * ```\n */\nexport function Message({\n  defaultMessage,\n  descriptor,\n  values,\n}: MessageProps): string {\n  const { translate } = useLocalize();\n  return translate(descriptor, values, defaultMessage);\n}\n"]}

package/package.json

@@ -1,38 +1,151 @@
 {
   "name": "localize-react",
-  "version": "1.6.0",
-  "description": "React Localization Library",
-  "main": "dist/localize-react.js",
-  "repository": "git@github.com:yankouskia/localize-react.git",
-  "author": "yankouskia <aleksandr.yankovskiy@gmail.com>",
+  "version": "2.0.0-next.0",
+  "description": "Tiny, type-safe React i18n library built on Context and hooks — dual ESM + CJS, zero runtime deps.",
+  "keywords": [
+    "react",
+    "i18n",
+    "l10n",
+    "localization",
+    "internationalization",
+    "translation",
+    "context",
+    "hooks",
+    "typescript"
+  ],
+  "homepage": "https://github.com/yankouskia/localize-react#readme",
+  "bugs": {
+    "url": "https://github.com/yankouskia/localize-react/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yankouskia/localize-react.git"
+  },
   "license": "MIT",
+  "author": {
+    "name": "Aliaksandr Yankouski",
+    "email": "aleksandr.yankovskiy@gmail.com",
+    "url": "https://github.com/yankouskia"
+  },
+  "funding": "https://github.com/sponsors/yankouskia",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "peerDependencies": {
-    "react": ">=16.8.0"
+    "react": ">=16.8.0 <20"
+  },
+  "engines": {
+    "node": ">=20.19.0"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm exec lint-staged"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "size-limit": [
+    {
+      "name": "ESM (full library)",
+      "path": "dist/index.mjs",
+      "limit": "2 kB",
+      "ignore": [
+        "react"
+      ]
+    },
+    {
+      "name": "CJS (full library)",
+      "path": "dist/index.cjs",
+      "limit": "2.5 kB",
+      "ignore": [
+        "react"
+      ]
+    }
+  ],
   "devDependencies": {
-    "@babel/core": "^7.5.5",
-    "@babel/plugin-transform-object-assign": "^7.2.0",
-    "@babel/preset-env": "^7.5.5",
-    "@babel/preset-react": "^7.0.0",
-    "babel-jest": "^24.8.0",
-    "babel-loader": "^8.0.6",
-    "codecov": "^3.5.0",
-    "jest": "^24.8.0",
-    "react": "^16.8.6",
-    "react-test-renderer": "^16.8.6",
-    "rollup": "^1.17.0",
-    "rollup-plugin-auto-external": "^2.0.0",
-    "rollup-plugin-babel": "^4.3.3",
-    "rollup-plugin-commonjs": "^10.0.1",
-    "rollup-plugin-node-resolve": "^5.2.0",
-    "rollup-plugin-replace": "^2.2.0",
-    "rollup-plugin-uglify": "^6.0.2"
+    "@arethetypeswrong/cli": "~0.18.2",
+    "@changesets/changelog-github": "0.5",
+    "@changesets/cli": "2.28",
+    "@eslint/js": "9",
+    "@microsoft/api-extractor": "7",
+    "@size-limit/preset-small-lib": "11",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16",
+    "@testing-library/user-event": "14",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "^4.1.6",
+    "eslint": "9",
+    "eslint-plugin-import-x": "4",
+    "eslint-plugin-n": "17",
+    "eslint-plugin-promise": "7",
+    "eslint-plugin-react": "7",
+    "eslint-plugin-react-hooks": "5",
+    "eslint-plugin-unicorn": "56",
+    "globals": "15",
+    "jsdom": "25",
+    "lint-staged": "15",
+    "prettier": "3",
+    "publint": "0.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "rimraf": "6",
+    "simple-git-hooks": "2",
+    "size-limit": "11",
+    "tsup": "8",
+    "typedoc": "~0.28.19",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "8",
+    "vite": "7",
+    "vitest": "^4.1.6"
   },
   "scripts": {
-    "build": "NODE_ENV=production rollup -c",
-    "test": "jest",
-    "coverage": "jest --coverage",
-    "codecov": "codecov -t 8365e97e-7298-4a00-ad32-740d44db89e5 -f coverage/*.json"
-  },
-  "types": "./index.d.ts"
-}
+    "build": "tsup",
+    "clean": "rimraf dist coverage .tsbuildinfo",
+    "dev": "tsup --watch",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "pack:check": "publint --strict",
+    "pack:check:types": "attw --pack . --ignore-rules cjs-resolves-to-esm",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "release": "changeset publish",
+    "version": "changeset version",
+    "size": "size-limit",
+    "docs": "typedoc"
+  }
+}

package/.babelrc

@@ -1,20 +0,0 @@
-{
-  "plugins": [
-    "@babel/plugin-transform-object-assign",
-  ],
-  "presets": [
-    [
-      "@babel/preset-env",
-      {
-        "targets": {
-          "browsers": [
-            "> 1%",
-            "safari >= 8",
-            "ie >= 11"
-          ]
-        }
-      }
-    ],
-    "@babel/preset-react"
-  ]
-}

package/dist/localize-react.js

@@ -1 +0,0 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports,require("react")):"function"==typeof define&&define.amd?define(["exports","react"],t):t((e=e||self)["localize-react"]={},e.React)}(this,function(e,s){"use strict";var p="default"in s?s.default:s;function v(e){return(v="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}var y={},d="[LOCALIZE-REACT]: There are no translations for specified locale",a="[LOCALIZE-REACT] Looks like template is being used, but no value passed for ",u=/{{([^{]+[^}])}}/g;function b(e,t){if(!t)return e;if(0===Object.keys(t).length)return e;var r,n,o,i=e.match(u);return i&&0!==i.length?(r=i,n=t,o=Object.keys(n),r.map(function(e){var t=Array.prototype.slice.call(e,2,-2).join(""),r=o.find(function(e){return e===t});return r?[e,n[r]]:(console.warn(a,e),[e,e])})).reduce(function(e,t){var r=new RegExp(t[0],"gi");return e.replace(r,t[1])},e):e}var g=p.createContext();var t=g.Consumer;function o(){return s.useContext(g)}e.LocalizationConsumer=t,e.LocalizationContext=g,e.LocalizationProvider=function(e){var t=e.children,r=e.disableCache,n=e.locale,o=e.translations,i=void 0===o?{}:o,a=function(e,t){if(!e)return null;if("object"===v(t[e]))return e;var r=e.toLowerCase().replace(/-/g,"_");if("object"===v(t[r]))return r;var n=r.split("_")[0];return"object"===v(t[n])?n:(console.warn(d,e),e)}(n,i),l=a?i[a]:i;function u(e,t,r){if(!l||!e)return r||e;var n="string"==typeof r?r:e,o=l[e];if("string"==typeof o)return t?b(o,t):o;var i=e.split(".");if(1===i.length)return b(n,t);for(var a=l[i[0]],u=1;u<i.length;u++)a=a&&a[i[u]];return b("string"==typeof a?a:n,t)}s.useEffect(function(){y={}},[n,i]);var c,f=r?u:(c=u,function(e,t,r){var n=2<arguments.length&&void 0!==r?r:"",o=t?JSON.stringify(t,null,"")+e+n:e+n;if(y[o])return y[o];var i=c(e,t,n);return y[o]=i});return p.createElement(g.Provider,{value:{locale:n,translate:f,translations:i}},t)},e.Message=function(e){var t=e.defaultMessage,r=e.descriptor,n=e.values;return(0,o().translate)(r,n,t)},e.useLocalize=o,Object.defineProperty(e,"__esModule",{value:!0})});