tomevault-io Localization
Configure
setRouterConfigurations({
localization: {
defaultLocaleCode: "en",
localeCodes: ["en", "fr", "es", "ar"],
changeLanguageReloadMode: "soft", // "soft" | "hard"
},
appendLocaleCodeToUrl: true, // default true
autoRedirectToLocaleCode: true, // default: localeCodes.length > 1
});
| Option | Effect |
|---|---|
defaultLocaleCode |
Used when autoRedirectToLocaleCode is on and the URL has no locale segment. |
localeCodes |
The set of allowed locale segments. URL parser only treats a segment as a locale if it's in this list. |
changeLanguageReloadMode |
Default mode for changeLocaleCode(code). "soft" re-renders; "hard" does window.location.href = …. |
appendLocaleCodeToUrl |
When false, the locale doesn't appear in the URL — useful for cookie/header-driven i18n. |
autoRedirectToLocaleCode |
When true and the URL has no locale segment, router.scan() redirects to defaultLocaleCode on first boot. |
URL shape
/basePath/(localeCode?)/appPath/routePath
Examples (with basePath: "/", app admin at /admin):
| User-facing URL | Parsed |
|---|---|
/ |
locale unset, app /, route / |
/en |
locale en, app /, route / |
/en/contact-us |
locale en, app /, route /contact-us |
/admin |
locale unset, app /admin, route / |
/en/admin/customers |
locale en, app /admin, route /customers |
When you call router.add("/customers", …), do NOT include the locale or the /admin prefix — they're prepended automatically based on the active app and locale.
Receiving the locale in a component
function UserPage({ params, localeCode }: { params: { id: string }; localeCode: string }) {
return <p>{t(localeCode, "userIs", { id: params.id })}</p>;
}
The locale also lives on router.getCurrentLocaleCode() for use outside the React tree.
Switching at runtime
import { changeLocaleCode } from "@mongez/react-router";
changeLocaleCode("fr"); // soft: fires localeCodeChanging, re-renders
changeLocaleCode("fr", "hard"); // hard: window.location.href = …
Soft
router.setCurrentLocaleCode(localeCode)- Fires
localeCodeChanging(new, old) - Refreshes the active route's
keyso the page remounts - Calls
router.goTo(...)with the new locale-prefixed URL, modechangeLocaleCode - Fires
localeChanged(new, old)
Listen for localeChanged to re-fetch locale-dependent data (translations, dates, currency).
Hard
Builds the full URL (with query string + hash preserved) and does window.location.href = fullPath. Used when you need a clean state across language changes (e.g. when third-party scripts cache locale state on init).
<Link> with locale
<Link to="/about">About</Link> // current locale automatically
<Link to="/about" localeCode="fr">À propos</Link> // explicit locale override
When no localeCode prop is set and the router currently has a locale code in the URL, <Link> uses it. Set localeCode explicitly to render a link to a different language (e.g. a language switcher).
Detecting the initial locale
The first time the URL contains a recognized locale segment, the router fires initialLocaleCode:
routerEvents.onDetectingInitialLocaleCode((localeCode) => {
console.log("Boot locale:", localeCode);
// good place to load translations, set <html lang>, etc.
});
This fires once per page load; subsequent locale changes fire localeChanging / localeChanged instead.
autoRedirectToLocaleCode default
If you don't set it, the router derives it: true when localeCodes.length > 1, otherwise false. The reasoning: single-locale apps never want a locale segment, multi-locale apps usually do.
Set it explicitly to override (e.g. false when you're driving i18n from a cookie and don't want it in the URL even with multiple locales).
Source: hassanzohdy/react-router — distributed by TomeVault.