react-i18next

  • Version 16.6.6
  • Published
  • 916 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 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 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 | Key;

                                                                                                          property i18n

                                                                                                          i18n?: i18n;

                                                                                                            property i18nKey

                                                                                                            i18nKey?: Key | readonly 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?: 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';

                                                                                                                                          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?: 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 (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>