TypeScript
Last updated
Last updated
i18next has embedded type definitions. If 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).
If your project spans multiple i18next instances with different translation resources, you probably can't use type-safe translations.
you'll find a simple guide on how to best use TypeScript for i18next. Discover how to unleash the full potential of i18next in your TypeScript applications by mastering type-safe translations, ensuring accurate localization and eliminating runtime errors.
Or, if you want to include all namespaces at once, you can use our preferred approach:
i18n.ts
i18next.d.ts
We recommend creating a @types
directory under src
or above it and placing all your type declarations there. E.g.: @types/i18next.d.ts
We provide a few options that can improve TypeScript for i18next
. All options come with default values, and if you want to change them, you just need to add them under CustomTypeOptions
interface in your i18next type declaration file (i18next.d.ts
).
defaultNS
'translation'
Default namespace. This is more practical in React applications, so when you call useTranslation()
hooks without passing the namespace, it will infer the types for the translation
namespace.
resources
object
Resources to initialize with. This is the most important option that is used to infer the appropriate keys and return types.
fallbackNS
false
keySeparator
'.'
Char to separate keys.
nsSeparator
':'
Char to split namespace from key
pluralSeparator
'_'
Char to split namespace from key
contextSeparator
'_'
Char to split context from key
returnNull
true
Allows null values as valid translation.
returnObjects
false
Allows objects as valid translation result
compatibilityJSON
'v4'
allowObjectInHTMLChildren
false
Flag that allows HTML elements to receive objects. This is only useful for React applications where you pass objects to HTML elements so they can be replaced to their respective interpolation values (mostly with Trans component)
interpolationPrefix
'{{'
Prefix for interpolation
interpolationSuffix
'}}'
Suffix for interpolation
strictKeyChecks
false
Flag that enables strict key checking even if a defaultValue
has been provided. This ensures all calls of t
function don't accidentally use implicitly missing keys.
Try to update the used TypeScript version (>= v5 is recommended).
Running typechecking with key validation might result in OOM errors. This can be facilitated by additional factors like:
large codebase with a lot of namespace with hundreds of keys
running typechecking alongside other tools like ESLint
combined with typescript-eslint
If you report a OOM error, please provide an easy way to reproduce the issue using:
online sandbox
example repository
Type 'HTMLAttributes<T>' is not assignable to type...
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):
Or:
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:
For now, this is the only possible workaround. This is a TypeScript limitation that will be address at some point in the future.
If you face this issue whenever calling the t
function:
TS2589: Type instantiation is excessively deep and possibly infinite.
react-i18next
only)If you are using the tagged template literal syntax for the t
function, like this:
t
function return when returnObjects
is set to true
but CustomTypeOptions.resources
is not used (>= v23)When no resources
are defined inside CustomTypeOptions
and returnObject
options is set to true
t
function returns a $SpecialObject
type:
Due to his anatomy it can be easily casted to a better defined type as you can see from the following examples:
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. If needed, you can always open an issue on Github to get some help from us.
TypeScript definitions for i18next can be extended by using and . So the first step is creating a declaration file (i18next.d.ts
), for example:
(from simple i18next only to react-i18next prod ready)
Fallback namespace. string or array of namespaces to lookup key if not found in given namespace. .
Only 'v4' is supported. Enable plurals keys support. See .
t
function infers interpolation values, but it'll only work if the translation files (resources) are placed in a ts file and using as const
(like ) or an (can be generated like ), JSON files don't support as const
to convert objects to be type literals (yet).
This happens when is disabled. Setting skipLibCheck
in tsconfig to true
will remove this issue.
That probably means you did not set up your type declaration correctly, so review your configuration or check for some similar cases that may help you. If needed, you can always open an issue on Github to get some help from us.
The keys
and return
type inference will not work, because does not accept generic types yet. You can use Tagged Template Literal syntax, but it will accept any string as argument.
t
function can return null
, this behaviour is , if you want to change it, set returnNull
type to false
.
I also recommend updating your to behave accordantly: