TypeScript

i18next localization as a service Find your translator
Search…
TypeScript
react-i18next has embedded type definitions. If your project is relying on TypeScript 4.1+, and you want to enhance IDE Experience and prevent errors (such as type coercion), you should follow the instructions below in order to get the t function fully-type safe (keys and return type).
This is an optional feature and was newly added in [email protected] Here you can see some examples of use.
Create a declaration file
TypeScript definitions for react-i18next can be extended by using Type Augmentation and Merging Interfaces. So the first step is creating a declaration file (react-i18next.d.ts), for example:
1
// import the original type declarations
2
import 'react-i18next';
3
// import all namespaces (for the default language, only)
4
import ns1 from 'locales/en/ns1.json';
5
import ns2 from 'locales/en/ns2.json';
6
​
7
​
8
// react-i18next versions lower than 11.11.0
9
declare module 'react-i18next' {
10
  // and extend them!
11
  interface Resources {
12
    ns1: typeof ns1;
13
    ns2: typeof ns2;
14
  }
15
}
16
​
17
// react-i18next versions higher than 11.11.0
18
declare module 'react-i18next' {
19
  // and extend them!
20
  interface CustomTypeOptions {
21
    // custom namespace type if you changed it
22
    defaultNS: 'ns1';
23
    // custom resources type
24
    resources: {
25
      ns1: typeof ns1;
26
      ns2: typeof ns2;
27
    };
28
  };
29
};
Copied!
Or, if you want to include all namespaces at once, you can use the following approach:
i18n.ts
1
export const defaultNS = 'ns1'
2
export const resources = {
3
  en: {
4
    ns1,
5
    ns2,
6
  },
7
} as const;
8
​
9
i18n.use(initReactI18next).init({
10
  lng: 'en',
11
  ns: ['ns1', 'ns2'],
12
  defaultNS,
13
  resources,
14
});
Copied!
react-i18next.d.ts
1
import { resources, defaultNS } from './i18n';
2
​
3
// react-i18next versions lower than 11.11.0
4
declare module 'react-i18next' {
5
  type DefaultResources = typeof resources['en'];
6
  interface Resources extends DefaultResources {}
7
}
8
​
9
// react-i18next versions higher than 11.11.0
10
declare module 'react-i18next' {
11
  interface CustomTypeOptions {
12
    defaultNS: typeof defaultNS;
13
    resources: typeof resources['en'];
14
  };
15
};
Copied!
That's all! Your t function should be fully typed by now.
Troubleshooting
Slow compilation time
In order to fully type the t function, we recursively map all nested keys from your primary locale files or objects. Depending on the number of keys your project have, the compilation time could be noticeably affected. If this is negatively influencing your productivity, this feature might not be the best choice for you. In our tests, we got great results when declaring up to 7000 keys, but it may vary according to the project size as well. If needed, you can always open an issue on Github to get some help from us.
Type errors
If you face this issue:
Argument of type 'string' is not assignable to parameter of type ...
When using the following approach (template literal with an expression):
1
const { t } = useTranslation();
2
t(`${expression}.title`);
Copied!
Or:
1
const { t } = useTranslation(`${ns}Default`);
Copied!
TypeScript will lose the literal value, and it will infer the key as string, which will cause to throw the error above. In this case, you will need to assert the template string as const, like this:
1
const { t } = useTranslation();
2
t(`${expression}.title` as const);
Copied!
For now, this is the only possible workaround. This is a TypeScript limitation which will be handled on TypeScript 4.2.
Tagged Template Literal
If you are using the tagged template literal syntax for the t function, like this:
1
t`key1.key2`;
Copied!
The keys and return type inference will not work, because TemplateStringsArray does not accept generic types yet. You can use Tagged Template Literal syntax, but it will accept any string as argument.
latest - Previous
Migrating v9 to v10
Next - Misc
Using with ICU format
Last modified 4mo ago
Copy link
Contents
Create a declaration file
Troubleshooting
Slow compilation time
Type errors
Tagged Template Literal