or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

components.mdhocs.mdhooks.mdicu-macro.mdindex.mdssr.md
tile.json

tessl/npm-react-i18next

React integration for i18next internationalization framework with hooks, components, and SSR support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-i18next@15.7.x

To install, run

npx @tessl/cli install tessl/npm-react-i18next@15.7.0

index.mddocs/

React i18next

React i18next provides comprehensive React integration for the i18next internationalization framework, enabling developers to build multilingual React applications with modern hooks, components, and server-side rendering support. It offers React-specific optimizations like automatic re-rendering when language or translations change, TypeScript support, and compatibility with both modern hooks-based and legacy class-based React components.

Package Information

  • Package Name: react-i18next
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install react-i18next i18next

Core Imports

import { useTranslation, Trans, I18nextProvider, initReactI18next } from "react-i18next";

For CommonJS:

const { useTranslation, Trans, I18nextProvider, initReactI18next } = require("react-i18next");

Specialized imports:

// Standalone Trans component without context
import { Trans } from "react-i18next/TransWithoutContext";

// i18next plugin initialization
import { initReactI18next } from "react-i18next/initReactI18next";

// ICU message format support (full API)
import { 
  Plural, 
  Select, 
  SelectOrdinal,
  plural, 
  select, 
  selectOrdinal,
  date,
  time,
  number
} from "react-i18next/icu.macro";

Basic Usage

import i18next from "i18next";
import { useTranslation, Trans, I18nextProvider, initReactI18next } from "react-i18next";

// Initialize i18next with React plugin
i18next
  .use(initReactI18next)
  .init({
    lng: "en",
    fallbackLng: "en",
    resources: {
      en: {
        translation: {
          welcome: "Welcome to React i18next!",
          greeting: "Hello, {{name}}!",
          itemCount: "You have {{count}} item",
          itemCount_other: "You have {{count}} items"
        }
      }
    }
  });

// Hook usage in components
function MyComponent() {
  const { t, i18n, ready } = useTranslation();
  
  if (!ready) return <div>Loading translations...</div>;
  
  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('greeting', { name: 'John' })}</p>
      <p>{t('itemCount', { count: 5 })}</p>
      
      {/* Complex translation with HTML using Trans component */}
      <Trans i18nKey="welcomeMessage" values={{ name: 'John' }}>
        Welcome back, <strong>{{name}}</strong>! Check your <a href="/inbox">messages</a>.
      </Trans>
      
      <button onClick={() => i18n.changeLanguage('de')}>
        Switch to German
      </button>
      <button onClick={() => i18n.changeLanguage('en')}>
        Switch to English
      </button>
    </div>
  );
}

// App setup with provider
function App() {
  return (
    <I18nextProvider i18n={i18next}>
      <MyComponent />
    </I18nextProvider>
  );
}

// Advanced usage with multiple namespaces and dynamic loading
function AdvancedExample() {
  const { t, i18n } = useTranslation(['common', 'navigation'], {
    keyPrefix: 'buttons',
    useSuspense: false
  });
  
  return (
    <div>
      <h1>{t('common:title')}</h1>
      <button>{t('save')}</button> {/* Uses keyPrefix: 'buttons.save' */}
      <nav>
        <a href="/">{t('navigation:home')}</a>
        <a href="/about">{t('navigation:about')}</a>
      </nav>
    </div>
  );
}

Architecture

React i18next is built around several key components:

  • React Hooks: useTranslation and useSSR for modern functional components
  • Context System: I18nextProvider and I18nContext for dependency injection
  • Component Layer: Trans for complex translations with HTML/React interpolation
  • HOC Pattern: withTranslation and withSSR for class components and legacy support
  • Plugin System: initReactI18next plugin integrates with i18next ecosystem
  • TypeScript Integration: Full type safety with generic namespace and key prefix support
  • SSR Support: Server-side rendering utilities for Next.js and other frameworks

Capabilities

React Hooks

Modern React hooks providing translation functions and i18next instance access with automatic re-rendering on language changes.

function useTranslation<Ns, KPrefix>(
  ns?: Ns,
  options?: UseTranslationOptions<KPrefix>
): UseTranslationResponse<Ns, KPrefix>;

interface UseTranslationOptions<KPrefix> {
  i18n?: i18n;
  useSuspense?: boolean;
  keyPrefix?: KPrefix;
  bindI18n?: string | false;
  nsMode?: 'fallback' | 'default';
  lng?: string;
}

type UseTranslationResponse<Ns, KPrefix> = [
  t: TFunction<Ns, KPrefix>,
  i18n: i18n,
  ready: boolean
] & {
  t: TFunction<Ns, KPrefix>;
  i18n: i18n;
  ready: boolean;
};

React Hooks

React Components

Components for rendering translations with HTML interpolation, provider context, and render prop patterns.

function Trans<Key, Ns, KPrefix, TContext, TOpt, E>(
  props: TransProps<Key, Ns, KPrefix, TContext, TOpt, E>
): React.ReactElement;

function I18nextProvider(props: I18nextProviderProps): React.FunctionComponent;

function Translation<Ns, KPrefix>(
  props: TranslationProps<Ns, KPrefix>
): React.ReactNode;

interface I18nextProviderProps {
  children?: React.ReactNode;
  i18n: i18n;
  defaultNS?: string | string[];
}

React Components

Higher-Order Components

HOCs for injecting translation functionality into class components and legacy React patterns.

function withTranslation<Ns, KPrefix>(
  ns?: Ns,
  options?: { withRef?: boolean; keyPrefix?: KPrefix }
): <C extends React.ComponentType<any>>(component: C) => React.ComponentType<any>;

function withSSR(): <Props>(
  WrappedComponent: React.ComponentType<Props>
) => React.ComponentType<Props & { initialI18nStore: Resource; initialLanguage: string }>;

Higher-Order Components

Server-Side Rendering

Utilities for server-side rendering support including initial data hydration and SSR-safe component rendering.

function useSSR(initialI18nStore: Resource, initialLanguage: string): void;

function composeInitialProps(ForComponent: any): (ctx: unknown) => Promise<any>;

function getInitialProps(): {
  initialI18nStore: { [ns: string]: {} };
  initialLanguage: string;
};

Server-Side Rendering

ICU Message Format Support

Babel macro providing compile-time ICU message format transformation with React component and template literal support.

// Template literal functions (compile-time)
function plural(strings: TemplateStringsArray, variable: number, ...args: ValidInterpolations[]): string;
function select(strings: TemplateStringsArray, variable: string, ...args: ValidInterpolations[]): string;
function date(strings: TemplateStringsArray, variable: Date): string;

// React components
function Plural<T, Key, Ns>(props: PluralProps<T, Key, Ns>): ReactElement;
function Select<Key, Ns>(props: SelectProps<Key, Ns>): ReactElement;

ICU Message Format

Standalone Components

Direct component imports without context dependency for advanced use cases and custom i18next configurations.

// TransWithoutContext - standalone Trans component
const TransWithoutContext: typeof Trans;

Core Types

// Core configuration and utilities
interface ReactOptions {
  bindI18n?: string | false;
  bindI18nStore?: string;
  transEmptyNodeValue?: string;
  transSupportBasicHtmlNodes?: boolean;
  transWrapTextNodes?: string;
  transKeepBasicHtmlNodesFor?: string[];
  useSuspense?: boolean;
  unescape?: (str: string) => string;
}

// Context and reporting
interface ReportNamespaces {
  addUsedNamespaces(namespaces: Namespace): void;
  getUsedNamespaces(): string[];
}

// Helper types for type system integration
type $Tuple<T> = readonly [T?, ...T[]];
type $Subtract<T extends K, K> = Omit<T, keyof K>;

// Error handling
type ErrorCode = 
  | 'NO_I18NEXT_INSTANCE'
  | 'NO_LANGUAGES'
  | 'DEPRECATED_OPTION'
  | 'TRANS_NULL_VALUE'
  | 'TRANS_INVALID_OBJ'
  | 'TRANS_INVALID_VAR'
  | 'TRANS_INVALID_COMPONENTS';

type ErrorArgs = readonly [string, ErrorMeta | undefined, ...any[]];

Configuration Functions

// Global defaults management
function setDefaults(options: ReactOptions): void;
function getDefaults(): ReactOptions;

// Global i18next instance management
function setI18n(instance: i18n): void;
function getI18n(): i18n;

// Plugin initialization
const initReactI18next: ThirdPartyModule;