tessl/npm-react-i18next

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

React i18next

Name: tessl/npm-react-i18next
Author: tessl

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;