react-i18next

  • Version 16.2.1
  • Published
  • 849 kB
  • 3 dependencies
  • MIT license

Install

npm i react-i18next
yarn add react-i18next
pnpm add react-i18next

Overview

Internationalization for react done right. Using the i18next i18n ecosystem.

Index

Variables

variable FlatNamespace

const FlatNamespace: any;

    variable FlatNamespace

    const FlatNamespace: any;

      variable I18nContext

      const I18nContext: React.Context<{ i18n: i18n }>;

        variable I18nextProvider

        const I18nextProvider: React.FunctionComponent<I18nextProviderProps>;

          variable IcuTrans

          const IcuTrans: IcuTransComponent;

            variable IcuTransWithoutContext

            const IcuTransWithoutContext: IcuTransWithoutContextComponent;

              variable initReactI18next

              const initReactI18next: ThirdPartyModule;

                variable KeyPrefix

                const KeyPrefix: any;

                  variable KPrefix

                  const KPrefix: any;

                    variable KPrefix

                    const KPrefix: any;

                      variable Ns

                      const Ns: any;

                        variable Ns

                        const Ns: any;

                          variable Trans

                          const Trans: TransSelector | TransLegacy;

                            variable TransWithoutContext

                            const TransWithoutContext: TransSelector | TransLegacy;

                              variable useTranslation

                              const useTranslation: UseTranslationLegacy;

                                Functions

                                function composeInitialProps

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

                                  function getDefaults

                                  getDefaults: () => ReactOptions;

                                    function getI18n

                                    getI18n: () => i18n;

                                      function getInitialProps

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

                                        function setDefaults

                                        setDefaults: (options: ReactOptions) => void;

                                          function setI18n

                                          setI18n: (instance: i18n) => void;

                                            function Translation

                                            Translation: <
                                            Ns extends unknown = undefined,
                                            KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined
                                            >(
                                            props: TranslationProps<Ns, KPrefix>
                                            ) => any;

                                              function useSSR

                                              useSSR: (initialI18nStore: Resource, initialLanguage: string) => void;

                                                function withSSR

                                                withSSR: () => <Props>(WrappedComponent: React.ComponentType<Props>) => {
                                                ({
                                                initialI18nStore,
                                                initialLanguage,
                                                ...rest
                                                }: {
                                                initialI18nStore: Resource;
                                                initialLanguage: string;
                                                } & Props): React.FunctionComponentElement<Props>;
                                                getInitialProps: (ctx: unknown) => Promise<any>;
                                                };

                                                  function withTranslation

                                                  withTranslation: <
                                                  Ns extends unknown = undefined,
                                                  KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined
                                                  >(
                                                  ns?: Ns,
                                                  options?: { withRef?: boolean; keyPrefix?: KPrefix }
                                                  ) => <
                                                  C extends React.ComponentType<any>,
                                                  ResolvedProps = React.JSX.LibraryManagedAttributes<
                                                  C,
                                                  $Subtract<React.ComponentProps<C>, WithTranslationProps>
                                                  >
                                                  >(
                                                  component: C
                                                  ) => React.ComponentType<
                                                  Omit<ResolvedProps, keyof WithTranslation<Ns, undefined>> & WithTranslationProps
                                                  >;

                                                    Interfaces

                                                    interface I18nextProviderProps

                                                    interface I18nextProviderProps {}

                                                      property children

                                                      children?: React.ReactNode;

                                                        property defaultNS

                                                        defaultNS?: string | string[];

                                                          property i18n

                                                          i18n: i18n;

                                                            interface IcuTransComponent

                                                            interface IcuTransComponent {}
                                                            • IcuTrans component for rendering ICU MessageFormat translations This is the context-aware version that works with I18nextProvider

                                                              Example 1

                                                              // Type-safe usage with namespace
                                                              <IcuTrans<'welcome.message', 'common'>
                                                              i18nKey="welcome.message"
                                                              defaultTranslation="Welcome <0>friend</0>!"
                                                              content={[{ type: 'strong', props: {} }]}
                                                              />

                                                            call signature

                                                            <
                                                            Key extends ParseKeys<Ns, TOpt, KPrefix> = string,
                                                            Ns extends Namespace = _DefaultNamespace,
                                                            KPrefix = undefined,
                                                            TContext extends string | undefined = undefined,
                                                            TOpt extends TOptions & { context?: TContext } = { context: TContext }
                                                            >(
                                                            props: IcuTransProps<Key, Ns, KPrefix, TContext, TOpt>
                                                            ): React.ReactElement;

                                                              interface IcuTransContentDeclaration

                                                              interface IcuTransContentDeclaration {}
                                                              • Content declaration for IcuTrans component Describes React components as type + props blueprints that will be rendered

                                                              property props

                                                              props?: {
                                                              children?: IcuTransContentDeclaration | IcuTransContentDeclaration[];
                                                              [key: string]: any;
                                                              };

                                                                property type

                                                                type: string | React.ComponentType<any>;

                                                                  interface IcuTransWithoutContextComponent

                                                                  interface IcuTransWithoutContextComponent {}
                                                                  • IcuTransWithoutContext component for rendering ICU MessageFormat translations This version does not use React context and requires explicit i18n instance

                                                                    Example 1

                                                                    // Type-safe usage with namespace
                                                                    <IcuTransWithoutContext<'welcome.message', 'common'>
                                                                    i18nKey="welcome.message"
                                                                    defaultTranslation="Welcome <0>back</0>!"
                                                                    content={[{ type: 'strong', props: {} }]}
                                                                    i18n={i18nInstance}
                                                                    />

                                                                  call signature

                                                                  <
                                                                  Key extends ParseKeys<Ns, TOpt, KPrefix> = string,
                                                                  Ns extends Namespace = _DefaultNamespace,
                                                                  KPrefix = undefined,
                                                                  TContext extends string | undefined = undefined,
                                                                  TOpt extends TOptions & { context?: TContext } = { context: TContext }
                                                                  >(
                                                                  props: IcuTransWithoutContextProps<Key, Ns, KPrefix, TContext, TOpt>
                                                                  ): React.ReactElement;

                                                                    interface ReportNamespaces

                                                                    interface ReportNamespaces {}

                                                                      method addUsedNamespaces

                                                                      addUsedNamespaces: (namespaces: Namespace) => void;

                                                                        method getUsedNamespaces

                                                                        getUsedNamespaces: () => string[];

                                                                          interface TranslationProps

                                                                          interface TranslationProps<
                                                                          Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined = undefined,
                                                                          KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined
                                                                          > {}

                                                                            property children

                                                                            children: (
                                                                            t: TFunction<FallbackNs<Ns>, KPrefix>,
                                                                            options: {
                                                                            i18n: i18n;
                                                                            lng: string;
                                                                            },
                                                                            ready: boolean
                                                                            ) => React.ReactNode;

                                                                              property i18n

                                                                              i18n?: i18n;

                                                                                property keyPrefix

                                                                                keyPrefix?: KPrefix;

                                                                                  property ns

                                                                                  ns?: Ns;

                                                                                    property nsMode

                                                                                    nsMode?: 'fallback' | 'default';

                                                                                      property useSuspense

                                                                                      useSuspense?: boolean;

                                                                                        interface TransSelectorProps

                                                                                        interface TransSelectorProps<
                                                                                        Key,
                                                                                        Ns extends Namespace = _DefaultNamespace,
                                                                                        KPrefix = undefined,
                                                                                        TContext extends string | undefined = undefined,
                                                                                        TOpt extends TOptions & { context?: TContext } = { context: TContext }
                                                                                        > {}

                                                                                          property children

                                                                                          children?: TransChild | readonly TransChild[];

                                                                                            property components

                                                                                            components?:
                                                                                            | readonly React.ReactElement[]
                                                                                            | { readonly [tagName: string]: React.ReactElement };

                                                                                              property context

                                                                                              context?: TContext;

                                                                                                property count

                                                                                                count?: number;

                                                                                                  property defaults

                                                                                                  defaults?: string;

                                                                                                    property i18n

                                                                                                    i18n?: i18n;

                                                                                                      property i18nKey

                                                                                                      i18nKey?: Key;

                                                                                                        property ns

                                                                                                        ns?: Ns;

                                                                                                          property parent

                                                                                                          parent?: string | React.ComponentType<any> | null;

                                                                                                            property shouldUnescape

                                                                                                            shouldUnescape?: boolean;

                                                                                                              property t

                                                                                                              t?: TFunction<Ns, KPrefix>;

                                                                                                                property tOptions

                                                                                                                tOptions?: TOpt;

                                                                                                                  property values

                                                                                                                  values?: {};

                                                                                                                    interface WithTranslation

                                                                                                                    interface WithTranslation<
                                                                                                                    Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined = undefined,
                                                                                                                    KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined
                                                                                                                    > {}

                                                                                                                      property i18n

                                                                                                                      i18n: i18n;

                                                                                                                        property t

                                                                                                                        t: TFunction<FallbackNs<Ns>, KPrefix>;

                                                                                                                          property tReady

                                                                                                                          tReady: boolean;

                                                                                                                            interface WithTranslationProps

                                                                                                                            interface WithTranslationProps {}

                                                                                                                              property i18n

                                                                                                                              i18n?: i18n;

                                                                                                                                property useSuspense

                                                                                                                                useSuspense?: boolean;

                                                                                                                                  Type Aliases

                                                                                                                                  type ErrorArgs

                                                                                                                                  type ErrorArgs = readonly [string, ErrorMeta | undefined, ...any[]];
                                                                                                                                  • Use to type the logger arguments

                                                                                                                                    Example 1

                                                                                                                                    import type { ErrorArgs } from 'react-i18next';
                                                                                                                                    const logger = {
                                                                                                                                    // ....
                                                                                                                                    warn: function (...args: ErrorArgs) {
                                                                                                                                    if (args[1]?.code === 'TRANS_INVALID_OBJ') {
                                                                                                                                    const [msg, { i18nKey, ...rest }] = args;
                                                                                                                                    return log(i18nKey, msg, rest);
                                                                                                                                    }
                                                                                                                                    log(...args);
                                                                                                                                    }
                                                                                                                                    }
                                                                                                                                    i18n.use(logger).use(i18nReactPlugin).init({...});

                                                                                                                                  type ErrorCode

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

                                                                                                                                    type FallbackNs

                                                                                                                                    type FallbackNs<Ns> = Ns extends undefined
                                                                                                                                    ? _DefaultNamespace
                                                                                                                                    : Ns extends Namespace
                                                                                                                                    ? Ns
                                                                                                                                    : _DefaultNamespace;

                                                                                                                                      type IcuTransProps

                                                                                                                                      type IcuTransProps<
                                                                                                                                      Key extends ParseKeys<Ns, TOpt, KPrefix> = string,
                                                                                                                                      Ns extends Namespace = _DefaultNamespace,
                                                                                                                                      KPrefix = undefined,
                                                                                                                                      TContext extends string | undefined = undefined,
                                                                                                                                      TOpt extends TOptions & { context?: TContext } = { context: TContext }
                                                                                                                                      > = IcuTransWithoutContextProps<Key, Ns, KPrefix, TContext, TOpt>;
                                                                                                                                      • Props for IcuTrans component (with React context support)

                                                                                                                                      type IcuTransWithoutContextProps

                                                                                                                                      type IcuTransWithoutContextProps<
                                                                                                                                      Key extends ParseKeys<Ns, TOpt, KPrefix> = string,
                                                                                                                                      Ns extends Namespace = _DefaultNamespace,
                                                                                                                                      KPrefix = undefined,
                                                                                                                                      TContext extends string | undefined = undefined,
                                                                                                                                      TOpt extends TOptions & { context?: TContext } = { context: TContext }
                                                                                                                                      > = {
                                                                                                                                      /** The i18n key to look up the translation */
                                                                                                                                      i18nKey: Key;
                                                                                                                                      /** The default translation in ICU format with numbered tags (e.g., "<0>Click here</0>") */
                                                                                                                                      defaultTranslation: string;
                                                                                                                                      /** Declaration tree describing React components and their props */
                                                                                                                                      content: IcuTransContentDeclaration[];
                                                                                                                                      /** Optional namespace(s) for the translation */
                                                                                                                                      ns?: Ns;
                                                                                                                                      /** Optional values for ICU variable interpolation */
                                                                                                                                      values?: Record<string, any>;
                                                                                                                                      /** i18next instance. If not provided, uses global instance */
                                                                                                                                      i18n?: i18n;
                                                                                                                                      /** Custom translation function */
                                                                                                                                      t?: TFunction<Ns, KPrefix>;
                                                                                                                                      };
                                                                                                                                      • Props for IcuTransWithoutContext component (no React context)

                                                                                                                                      type TransProps

                                                                                                                                      type TransProps<
                                                                                                                                      Key extends ParseKeys<Ns, TOpt, KPrefix>,
                                                                                                                                      Ns extends Namespace = _DefaultNamespace,
                                                                                                                                      KPrefix = undefined,
                                                                                                                                      TContext extends string | undefined = undefined,
                                                                                                                                      TOpt extends TOptions & { context?: TContext } = { context: TContext },
                                                                                                                                      E = React.HTMLProps<HTMLDivElement>
                                                                                                                                      > = E & {
                                                                                                                                      children?: TransChild | readonly TransChild[];
                                                                                                                                      components?:
                                                                                                                                      | readonly React.ReactElement[]
                                                                                                                                      | { readonly [tagName: string]: React.ReactElement };
                                                                                                                                      count?: number;
                                                                                                                                      context?: TContext;
                                                                                                                                      defaults?: string;
                                                                                                                                      i18n?: i18n;
                                                                                                                                      i18nKey?: Key | Key[];
                                                                                                                                      ns?: Ns;
                                                                                                                                      parent?: string | React.ComponentType<any> | null; // used in React.createElement if not null
                                                                                                                                      tOptions?: TOpt;
                                                                                                                                      values?: {};
                                                                                                                                      shouldUnescape?: boolean;
                                                                                                                                      t?: TFunction<Ns, KPrefix>;
                                                                                                                                      };

                                                                                                                                        type UseTranslationOptions

                                                                                                                                        type UseTranslationOptions<KPrefix> = {
                                                                                                                                        i18n?: i18n;
                                                                                                                                        useSuspense?: boolean;
                                                                                                                                        keyPrefix?: KPrefix;
                                                                                                                                        bindI18n?: string | false;
                                                                                                                                        nsMode?: 'fallback' | 'default';
                                                                                                                                        lng?: string;
                                                                                                                                        // other of these options might also work: https://github.com/i18next/i18next/blob/master/index.d.ts#L127
                                                                                                                                        };

                                                                                                                                          type UseTranslationResponse

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

                                                                                                                                            Package Files (3)

                                                                                                                                            Dependencies (3)

                                                                                                                                            Dev Dependencies (51)

                                                                                                                                            Peer Dependencies (3)

                                                                                                                                            Badge

                                                                                                                                            To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                                                                                            You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/react-i18next.

                                                                                                                                            • Markdown
                                                                                                                                              [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/react-i18next)
                                                                                                                                            • HTML
                                                                                                                                              <a href="https://www.jsdocs.io/package/react-i18next"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>