Localization

@granit/localization provides framework-agnostic i18next configuration for loading translations from the .NET backend — mirroring Granit.Localization. It handles locale detection (localStorage → user setting → browser → default), i18next instance creation, and backend response application.

@granit/react-localization adds React integration with initReactI18next, a useLocale hook for language switchers, and re-exports useTranslation, Trans, and I18nextProvider from react-i18next.

Peer dependencies: i18next, react-i18next, react ^19

Package structure

• Directory@granit/localization/ i18next factory, locale resolution, translation loader (framework-agnostic)

  • @granit/react-localization React factory, useLocale hook, react-i18next re-exports

Package	Role	Depends on
@granit/localization	createLocalization, resolveInitialLocale, applyTranslations	i18next
@granit/react-localization	createReactLocalization, useLocale, re-exports	@granit/localization, react-i18next, react

Setup

React (recommended)

import { createReactLocalization } from '@granit/react-localization';
import { I18nextProvider } from '@granit/react-localization';
import { applyTranslations } from '@granit/localization';

const i18n = createReactLocalization();

// After fetching translations from the backend:
const data = await fetch('/api/v1/localization?cultureName=fr');
applyTranslations(i18n, data);

function App({ children }) {
  return (
    <I18nextProvider i18n={i18n}>
      {children}
    </I18nextProvider>
  );
}

TypeScript only

import { createLocalization, resolveInitialLocale, applyTranslations } from '@granit/localization';
import type { LanguageInfo, ApplicationLocalizationDto } from '@granit/localization';

const i18n = createLocalization();
const locale = resolveInitialLocale();
// Fetch translations for resolved locale...

TypeScript SDK

Types

interface LanguageInfo {
  cultureName: string;
  displayName: string;
  flagIcon?: string;
  isDefault: boolean;
}

interface ApplicationLocalizationDto {
  cultureName: string;
  resources: Record<string, Record<string, string>>;
  languages: LanguageInfo[];
}

interface LocalizationConfig {
  storageKey?: string;      // localStorage key (default: 'locale' → dd:locale)
  defaultNS?: string;       // i18next namespace (default: 'translation')
  plugins?: Module[];       // i18next plugins (e.g. initReactI18next)
}

Functions

createLocalization(config?)

Creates an isolated i18next instance (not the global singleton). The instance is initialized without a lng option — the locale is resolved separately and applied via applyTranslations.

function createLocalization(config?: LocalizationConfig): i18n;

resolveInitialLocale(languages?, storageKey?, userLocale?)

Resolves the initial locale before backend data is available.

Detection cascade:

1. localStorage (dd:locale) — if present, use it
2. userLocale from user settings — if provided, use it
3. navigator.language — try exact match, then base code
4. languages array — use the one with isDefault: true
5. Fallback: 'fr'

function resolveInitialLocale(
  languages?: LanguageInfo[],
  storageKey?: string,
  userLocale?: string | null
): string;

applyTranslations(instance, data)

Applies the backend response to the i18next instance. Backend resources are grouped by module (e.g. { "Granit": {...}, "Guava": {...} }) — this function merges them into the single translation namespace.

function applyTranslations(instance: i18n, data: ApplicationLocalizationDto): void;

Constants

const LOCALE_STORAGE_KEY = 'locale';  // prefixed as dd:locale by @granit/storage

React bindings

Framework-agnostic core

All types, the i18next factory, locale resolution, and translation application live in @granit/localization — pure TypeScript. The React package below adds React integration.

createReactLocalization(config?)

Convenience wrapper that injects initReactI18next as a plugin automatically.

function createReactLocalization(
  config?: Omit<LocalizationConfig, 'plugins'>
): i18n;

useLocale(options?)

Hook for language switchers. Returns the current locale and a setter that persists to localStorage, updates i18next, and optionally notifies the backend.

interface UseLocaleOptions {
  onLocaleChange?: (locale: string) => void;
}

function useLocale(options?: UseLocaleOptions): {
  locale: string;
  setLocale: (locale: string) => void;
};

Re-exports

For convenience, the following are re-exported from react-i18next:

• I18nextProvider — Wrap your app to provide the i18next instance
• useTranslation — Access translations in components
• Trans — Component for interpolated translations with JSX

Public API summary

Category	Key exports	Package
Types	LanguageInfo, ApplicationLocalizationDto, LocalizationConfig	@granit/localization
Factory	createLocalization()	@granit/localization
Locale resolution	resolveInitialLocale(), LOCALE_STORAGE_KEY	@granit/localization
Translation loader	applyTranslations()	@granit/localization
React factory	createReactLocalization()	@granit/react-localization
Locale hook	useLocale()	@granit/react-localization
Re-exports	I18nextProvider, useTranslation, Trans	@granit/react-localization

See also

• Granit.Localization module — .NET i18n with 17 cultures, override store, and source-generated keys
• Settings — SETTING_NAMES.PREFERRED_CULTURE stores the user’s language preference
• Reference Data — Country labels use the same multilingual pattern