Skip to content
Mongez — production TypeScript packages Mongez

React Localization

The React-side bridge for @mongez/localization. Does one thing: replace :placeholder (or {{placeholder}}) tokens in a translation with React children, so you can drop <strong>, <a href>, or any element straight into a translated sentence. Small on purpose — two exports.

Highlighted features

jsxConverter

The placeholder-to-React converter. Wire it globally via setLocalizationConfigurations({ converter: jsxConverter }) and every trans understands JSX placeholders.

transX per call

Keep trans strongly typed as string for the 99% of call sites that don’t need JSX, drop down to transX when you do.

Same placeholder pattern

JSX placeholders use the same :name (or custom regex) markers as plain text — no second template syntax to learn.

Two exports, no hooks

Plain functions. No useLocale, no <Translate>, no subscription layer — drive re-renders from your own state library.

Install

Terminal window
npm install @mongez/react-localization @mongez/localization

Peer deps: @mongez/localization >= 3.4.0, react >= 18.

Quick peek

import { extend, setLocalizationConfigurations, trans } from "@mongez/localization";
import { jsxConverter } from "@mongez/react-localization";


setLocalizationConfigurations({ converter: jsxConverter });
extend("en", { agreeToTerms: "You agree to our :tos." });


<p>{trans("agreeToTerms", { tos: <a href="/terms">Terms</a> })}</p>
// → <p>You agree to our <a href="/terms">Terms</a>.</p>

Wire jsxConverter once at boot, then drop React elements straight into translated sentences as placeholder values.

The two paths

Path A: wire jsxConverter globally

import { setLocalizationConfigurations } from "@mongez/localization";
import { jsxConverter } from "@mongez/react-localization";


setLocalizationConfigurations({
  defaultLocaleCode: "en",
  fallback: "en",
  converter: jsxConverter,
});

Every trans(...) understands JSX placeholders. The return type widens to string | React.ReactNode[].

Path B: keep the default converter, use transX per call

import { trans } from "@mongez/localization";
import { transX } from "@mongez/react-localization";


trans("greeting");                              // → "Hello" (string)
trans("greeting", { name: "Alice" });           // → "Hello Alice" (string)
transX("greeting", { name: <em>Alice</em> });   // → React fragment array

This path keeps trans strongly typed as string for everything else.

What this package is NOT

  • Not a hooks library. No useLocale, useTranslate, <Translate>.
  • Not a subscription layer. setCurrentLocaleCode("ar") does NOT re-render components that already rendered. Drive re-renders from a parent state.
  • Not a registry. Translations live in @mongez/localization’s module state. Call extend("en", {...}) from the core package.

Where to go next

  • transX — per-call JSX-aware translation
  • JSX converter — global wiring, placeholder mechanics
  • Recipes — common patterns (link injection, formatting, dynamic locale switching)
  • Localization core — extend, trans, locale switching, plural rules