react-i18next

  • Version 16.5.4
  • Published
  • 891 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 nodesToString

                                        nodesToString: (
                                        children: React.ReactNode,
                                        i18nOptions?: ReactOptions,
                                        i18n?: i18n,
                                        i18nKey?: string
                                        ) => 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>,
                                                              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>,
                                                                    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>,
                                                                                                                                        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>,
                                                                                                                                        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>