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`

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>
  );
}

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:

localStorage (dd:locale) — if present, use it
userLocale from user settings — if provided, use it
navigator.language — try exact match, then base code
languages array — use the one with isDefault: true
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

`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`