react-i18next

  • Version 17.1.13
  • Published
  • 1.06 MB
  • 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 Key

                const Key: any;

                  variable Key

                  const Key: any;

                    variable KeyPrefix

                    const KeyPrefix: any;

                      variable KeyPrefixSelector

                      const KeyPrefixSelector: any;

                        variable KPrefix

                        const KPrefix: any;

                          variable KPrefix

                          const KPrefix: any;

                            variable KPrefix

                            const KPrefix: any;

                              variable Ns

                              const Ns: any;

                                variable Ns

                                const Ns: any;

                                  variable ParseKeys

                                  const ParseKeys: any;

                                    variable ParseKeys

                                    const ParseKeys: 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: {} }]}
                                                                            />

                                                                          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}
                                                                                />

                                                                              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 | Key;

                                                                                                              property i18n

                                                                                                              i18n?: i18n;

                                                                                                                property i18nKey

                                                                                                                i18nKey?: Key | readonly Key[];

                                                                                                                  property ns

                                                                                                                  ns?: Ns | (Ns extends readonly (infer S extends string)[] ? S : never);

                                                                                                                    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?: Key extends (...args: any[]) => infer R ? InterpolationMap<R> : {};

                                                                                                                              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'
                                                                                                                                            | 'USE_T_BEFORE_READY'
                                                                                                                                            | 'SUSPENDED_WHILE_LOADING';

                                                                                                                                              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 */
                                                                                                                                                // see TransProps.ns: keep single-namespace values assignable when `t` fixes Ns to an array
                                                                                                                                                ns?: Ns | (Ns extends readonly (infer S extends string)[] ? S : never);
                                                                                                                                                /**
                                                                                                                                                * Values for ICU variable interpolation. Under `parseInterpolation: 'icu'`
                                                                                                                                                * (or `'mf2'`) they are typed from the message.
                                                                                                                                                */
                                                                                                                                                values?: [TypeOptions['parseInterpolation']] extends ['icu'] | ['mf2']
                                                                                                                                                ? InterpolationMap<
                                                                                                                                                TFunctionReturn<
                                                                                                                                                Ns,
                                                                                                                                                KPrefix extends string
                                                                                                                                                ? `${KPrefix}${TypeOptions['keySeparator']}${Key & string}`
                                                                                                                                                : Key,
                                                                                                                                                TOpt
                                                                                                                                                >
                                                                                                                                                >
                                                                                                                                                : 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[];
                                                                                                                                                // allow a single namespace from an array-typed `t` (e.g. useTranslation(['ns'])); TS7 intersects
                                                                                                                                                // inference candidates from `t` and `ns`, so a bare `Ns` here rejects ns="ns" when t is passed
                                                                                                                                                ns?: Ns | (Ns extends readonly (infer S extends string)[] ? S : never);
                                                                                                                                                parent?: string | React.ComponentType<any> | null; // used in React.createElement if not null
                                                                                                                                                tOptions?: TOpt;
                                                                                                                                                // keep the return type inside this property: as a type parameter of `Trans`, it was also
                                                                                                                                                // computed for every key of the namespace, which is slow with large resources
                                                                                                                                                values?: InterpolationMap<
                                                                                                                                                TFunctionReturn<Ns, _AppendKeyPrefix<Key, KPrefix>, TOpt>
                                                                                                                                                >;
                                                                                                                                                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 (37)

                                                                                                                                                      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>