Overview

@stackra/react-i18n is a full-fledged internationalization system for React + Vite projects. Built on i18next, it integrates with the @stackra/ts-container DI system, the @stackra/ts-http middleware pipeline, and follows the same architectural patterns as @stackra/react-multitenancy.

Key highlights:

• DI Module — I18nModule.forRoot() registers services, resolvers, and middleware
• Injectable Service — I18nService provides t(), changeLocale(), resolveLocale(), isRTL()
• React Hooks — useLocale(), useTranslation(), useChangeLocale()
• Locale Resolver Chain — pluggable resolvers (URL path, query param, storage, navigator, HTTP header)
• HTTP Middleware — LocaleMiddleware injects Accept-Language and syncs Content-Language
• Vite Plugin — auto-discovery, type generation, HMR for translation files
• Zero-import globals — __('key'), t('key') available on globalThis

Installation

pnpm add @stackra/react-i18n

Peer dependencies: vite, @stackra/ts-container, @stackra/ts-http (optional, for middleware).

Architecture

I18nModule.forRoot(config)
  ├── I18N_CONFIG          — merged module configuration
  ├── I18NEXT_SERVICE      — I18nextService (i18next singleton wrapper)
  ├── LOCALE_RESOLVER_CHAIN — composed resolver chain function
  ├── I18N_SERVICE         — I18nService (high-level @Injectable)
  ├── 5 resolver tokens    — factory-created from config
  └── LocaleMiddleware     — @HttpMiddleware for HTTP pipeline

<I18nProvider service={i18nService}>
  ├── resolves initial locale on mount
  ├── useLocale()          — { locale, languages, isRTL }
  ├── useTranslation()     — { t, __, trans }
  └── useChangeLocale()    — { changeLocale, isChanging, error }

Module Setup

import { Module } from '@stackra/ts-container';
import { I18nModule } from '@stackra/react-i18n';

@Module({
  imports: [
    I18nModule.forRoot({
      defaultLanguage: 'en',
      languages: ['en', 'ar', 'es'],
      resolvers: ['url-path', 'storage', 'navigator'],
      storageKey: 'i18nextLng',
      queryParam: 'lang',
    }),
  ],
})
export class AppModule {}

React Provider Setup

import { ContainerProvider } from '@stackra/ts-container';
import { I18nProvider } from '@stackra/react-i18n';

// I18nProvider uses useInject(I18N_SERVICE) internally —
// just nest it inside ContainerProvider, no manual wiring needed.
// RTL direction (document.dir) and document.lang are set automatically.
const App = () => (
  <ContainerProvider context={app}>
    <I18nProvider>
      <MyApp />
    </I18nProvider>
  </ContainerProvider>
);

Hooks

useTranslation

import { useTranslation } from '@stackra/react-i18n';

const Greeting = () => {
  const { t } = useTranslation();
  return <h1>{t('greeting', { name: 'John' })}</h1>;
};

useLocale

import { useLocale } from '@stackra/react-i18n';

const LanguageInfo = () => {
  const { locale, languages, isRTL } = useLocale();
  return <div dir={isRTL ? 'rtl' : 'ltr'}>Current: {locale}</div>;
};

useChangeLocale

import { useLocale, useChangeLocale } from '@stackra/react-i18n';

const LanguageSwitcher = () => {
  const { locale, languages } = useLocale();
  const { changeLocale, isChanging } = useChangeLocale();

  return (
    <select
      value={locale}
      onChange={(e) => changeLocale(e.target.value)}
      disabled={isChanging}
    >
      {languages.map((lang) => (
        <option key={lang} value={lang}>
          {lang}
        </option>
      ))}
    </select>
  );
};

Injecting the Service

import { Injectable, Inject } from '@stackra/ts-container';
import { I18N_SERVICE } from '@stackra/react-i18n';
import type { II18nService } from '@stackra/react-i18n';

@Injectable()
class NotificationService {
  constructor(@Inject(I18N_SERVICE) private i18n: II18nService) {}

  notify(key: string): void {
    showToast(this.i18n.t(key));
  }
}

Locale Resolvers

Resolvers detect the user's locale from various sources. They are tried in priority order (lower = higher priority). The first to return a value wins.

| Priority | Resolver | Source | | ----------- | ----------------- | --------------------------------- | | 1 (HIGHEST) | url-path | URL path segment (/ar/products) | | 2 (HIGH) | query-param | Query parameter (?lang=ar) | | 3 (NORMAL) | storage | localStorage / sessionStorage | | 4 (LOW) | accept-language | Stored HTTP response header | | 5 (LOWEST) | navigator | Browser navigator.language |

Custom Resolvers

import type { ILocaleResolver } from '@stackra/react-i18n';
import { LocaleResolverPriority } from '@stackra/react-i18n';

class JwtLocaleResolver implements ILocaleResolver {
  name = 'jwt';
  priority = LocaleResolverPriority.HIGHEST;

  resolve(): string | undefined {
    const token = getAccessToken();
    return token ? decodeJwt(token).locale : undefined;
  }
}

// Register in module config
I18nModule.forRoot({
  resolvers: ['jwt', 'url-path', 'storage', 'navigator'],
  customResolvers: { jwt: new JwtLocaleResolver() },
});

HTTP Middleware

The LocaleMiddleware integrates with @stackra/ts-http:

• Injects Accept-Language header on every outgoing request
• Reads Content-Language from API responses and syncs back
• Opt out per-request with meta: { skipLocale: true }

Registered automatically by I18nModule.forRoot(). Uses @HttpMiddleware({ priority: 15 }).

Vite Plugin

For build-time translation scanning (separate from the DI system):

import { defineConfig } from 'vite';
import { i18nPlugin } from '@stackra/react-i18n';

export default defineConfig({
  plugins: [
    i18nPlugin({
      defaultLanguage: 'en',
      languages: ['en', 'ar', 'es'],
      typeGeneration: true,
    }),
  ],
});

Features: auto-discovery via glob, TypeScript type generation, HMR for translation files, virtual module (virtual:@stackra/react-i18n).

Module Options

| Option | Type | Default | Description | | ------------------ | --------------------------------- | -------------------------- | ----------------------------- | | defaultLanguage | string | 'en' | Fallback language | | languages | string[] | ['en'] | Supported language codes | | resolvers | string[] | ['storage', 'navigator'] | Active resolver names | | customResolvers | Record<string, ILocaleResolver> | {} | Custom resolver instances | | queryParam | string | 'lang' | Query parameter name | | storageKey | string | 'i18nextLng' | localStorage key | | requestHeader | string | 'Accept-Language' | Outgoing request header | | responseHeader | string | 'content-language' | Incoming response header | | syncFromResponse | boolean | true | Sync locale from API response | | i18nextOptions | Partial<I18nextOptions> | {} | Pass-through i18next config | | debug | boolean | false | Enable debug logging |

DI Tokens

| Token | Resolves To | | --------------------------------- | -------------------------------------------- | | I18N_CONFIG | I18nModuleOptions — merged config | | I18N_SERVICE | I18nService — high-level service | | I18NEXT_SERVICE | I18nextService — low-level i18next wrapper | | LOCALE_RESOLVER_CHAIN | () => Promise<string \| undefined> | | URL_PATH_LOCALE_RESOLVER | UrlPathLocaleResolver | | QUERY_PARAM_LOCALE_RESOLVER | QueryParamLocaleResolver | | STORAGE_LOCALE_RESOLVER | StorageLocaleResolver | | NAVIGATOR_LOCALE_RESOLVER | NavigatorLocaleResolver | | ACCEPT_LANGUAGE_LOCALE_RESOLVER | AcceptLanguageLocaleResolver |

License

MIT