localization-gen-react-adapter

React adapter for consuming localization manifests generated by localization-gen-core.

What it provides

• LocalizationProvider – context provider that wraps your app
• useLocalization – locale/manifest access + high-level translation helpers
• useAppLocalization – structured accessor hook (runtime translated values)
• Runtime bridge store for locale switching
• Lazy/SSR helpers

Install

npm install localization-gen-react-adapter localization-gen-core react

Setup

import LocalizationProvider from "localization-gen-react-adapter";
import appLocalizationManifest from "./assets/localizations/app-localization";

<LocalizationProvider manifest={appLocalizationManifest}>
  <App />
</LocalizationProvider>;

Usage with useLocalization

Use the generated appLocalization constant for type-safe key references:

import { useLocalization } from "localization-gen-react-adapter";
import { appLocalization } from "./assets/localizations/app-localization";

const {
  locale,
  setLocale,
  manifest,
  translate,   // plain string helper with locale fallback + optional fallback value
  format,      // helper + placeholder interpolation
  plural,      // structured plural helper
  gender,      // structured gender helper
  context,     // structured context helper
  namespace,   // creates a module-scoped helper object
  entriesForLocale,
} = useLocalization({
  fallback: {
    [appLocalization.auth.strings.login_title]: "Login",
    [appLocalization.common.app_title]: "App",
  },
});

// Top-level helpers — keys are always type-safe via appLocalization.*
translate(appLocalization.auth.strings.login_title);
format(appLocalization.auth.placeholders.welcome_back, { name: "Alfin" });
plural(appLocalization.auth.structured.lock_message, 3);
gender(appLocalization.common.structured.user_title, "female", { last_name: "Smith" });
context(appLocalization.auth.structured.channel_label, "email");

// Optional per-call fallback still works (overrides configured fallback)
translate(appLocalization.auth.strings.login_title, "Sign In");

// Namespace-scoped helpers (keys are relative to the module)
const authNs = namespace("auth");
authNs.translate("strings.login_title");
authNs.format("placeholders.welcome_back", { name: "Alfin" });
authNs.plural("structured.lock_message", 3);
authNs.gender("structured.account_title", "other", { last_name: "Doe" });
authNs.context("structured.channel_label", "email");

Usage with useAppLocalization

useAppLocalization returns a runtime accessor with actual translated strings (not key references). The accessor tree strips the module prefix so keys are relative to their module:

import { useAppLocalization } from "localization-gen-react-adapter";

const { strings, placeholders } = useAppLocalization();

// strings — plain values resolved for the active locale
strings.auth?.strings?.login_title;        // e.g. "Sign In"
strings.common?.app_title;                 // e.g. "My App"

// placeholders — functions that interpolate and return the translated string
placeholders.auth?.placeholders?.welcome_back({ name: "Alfin" }); // e.g. "Welcome, Alfin!"

Tip: For type-safe key access (not translated values), import appLocalization from the generated app-localization.ts file and pass keys to translate/format/plural/gender/context.

Release

npm run release:check
npm run release:pack
npm run release:dry-run
npm run release:pack:clean