On this page
Configuration
The options of i18next.config.ts: where the keys are read, where the files go and how each command behaves.
The configuration is i18next.config.ts or i18next.config.js. The defineConfig helper adds types and editor completion and nothing else.
Basic configuration
// i18next.config.ts
import { defineConfig } from 'i18next-cli';
export default defineConfig({
locales: ['en', 'de', 'fr'],
extract: {
input: ['src/**/*.{ts,tsx,js,jsx}'],
output: 'locales/{{language}}/{{namespace}}.json',
},
});
Without defineConfig, a plain object works the same, for example when i18next-cli is not installed in the project:
// i18next.config.js
export default {
locales: ['en', 'de', 'fr'],
extract: {
input: ['src/**/*.{ts,tsx,js,jsx}'],
output: 'locales/{{language}}/{{namespace}}.json',
},
};
Only JavaScript and TypeScript files (.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts) are extracted. Other file types (.vue, .astro, .pug) need a plugin.
Options
Only locales, extract.input and extract.output are required. In i18next.config.ts your editor completes the rest.
locales(required): the language codes, for example['en', 'de', 'fr'].plugins(default[]): see Plugin system.
extract
input(required): glob pattern(s) of the files to read.output(required): the path of the translation files, with{{language}}and{{namespace}}, or a function(language, namespace) => path.ignore(no default): glob pattern(s) of files to leave out.outputFormat(default'json'):'json5'(comments, trailing commas and formatting kept where possible),'yaml','js','js-esm','js-cjs'or'ts'(a module withexport default). Anoutputending in.json5,.yamlor.ymlpicks its format by itself.mergeNamespaces(defaultfalse): one file per language, with the namespaces as top-level keys;outputthen has no{{namespace}}.functions(default['t', '*.t']): the translation functions to look for. A leading*matches any object ('*.t'matchesi18n.t), a trailing*any method ('tProps.*'matchestProps.label).transComponents(default['Trans']): the components whose children are translations.transKeepBasicHtmlNodesFor(default['br', 'strong', 'i', 'p']): the HTML tags kept by name in the default text of aTrans.useTranslationNames(default['useTranslation', 'getT', 'useT']): the functions that return at. A name takes the namespace as first argument and the options withkeyPrefixas second; an object sets other positions:{ name: 'loadPageTranslations', nsArg: 1, keyPrefixArg: 2 }.defaultNS(default'translation'): the namespace of keys that name none;falsewrites no namespace, for example for one file per language without nesting.fallbackNS(no default): the namespace or namespaces to fall back to, as in i18next; keys translated there are not copied into other namespace files.nsSeparator(default':'),keySeparator(default'.',falsefor flat keys),contextSeparatorandpluralSeparator(default'_').preservePatterns(no default): keysextractkeeps although the code does not use them, as patterns with an optional namespace:'dynamic.feature.*','assets:*'(every key ofassets),'dynamic:user.*.profile'.preserveContextVariants(defaultfalse): keeps every context variant of a key that is used withcontext(friend_male,friend_female), and adds them to every language.sort(defaulttrue): sorts the keys;falsekeeps their order, a function(a, b) => numbersets your own.'locize'sorts by plain character code, the order of the files Locize publishes, soextractfollowed bylocize-syncorlocize-downloadshows no reordering in the diff.indentation(default2): spaces, or a string.primaryLanguage(default: the first oflocales) andsecondaryLanguages(default: all others).omitMissingKeys(defaultfalse): the languages (ortruefor all secondary ones) that get no empty placeholder for a new key, so i18next falls back tofallbackLngat run time. Existing translations stay, unused keys still go, andstatusstill counts the missing ones; empty strings already in these files stay until you remove them.defaultValue(default''): the value of a missing key in secondary languages, or a function(key, namespace, language, value) => string, for example(key) => `TODO: translate ${key}`.removeUnusedKeys(defaulttrue): removes the keys the code no longer uses.ignoreNamespaces(no default): namespaces thatextract,statusandsyncleave alone, with*as a wildcard ('dev.*'), for example namespaces shared in a monorepo. Such a namespace still serves asfallbackNS: it is read, never written.extractFromComments(defaulttrue): also readst()andTransin code comments.maxTypeDepth(default5): how many levels of nested members a dynamic key follows into a typed value; more levels cost time and memory with large recursive types such as OpenAPI schemas.generateBasePluralForms(defaulttrue): withfalse,t('key', { context: 'male', count: 1 })writes onlykey_male_oneandkey_male_other, notkey_oneandkey_other.disablePlurals(defaultfalse): writes no plural forms;countstill fills{{count}}.allPluralForms(defaultfalse): gives every language the plural forms of all languages (withenandpl, English gets_fewand_manyas well).nestingPrefix(default'$t('),nestingSuffix(default')') andnestingOptionsSeparator(default','): how$t(...)nesting is written. A key reached only through$t(...), in the code or in a translation, is kept.interpolationPrefix(default'{{') andinterpolationSuffix(default'}}').messageFormat(default'i18next'):'icu'or'mf2'for i18next-icu or i18next-mf2; see ICU and MF2 messages.instrumentScorer(no default): your own confidence score forinstrument; see Custom scorer hook.acceptedAttributes,acceptedTags,ignoredAttributes,ignoredTags: as underlint, for bothinstrumentandlint; see Translatable attributes per element.warnOnConflicts(defaultfalse):'warn'or'error'when the same key is extracted with different default values.warnOnAmbiguousTypes(defaultfalse):'warn'or'error'when the extractor has to guess which of several declarations of a type, enum or constant a dynamic key means.
lint
acceptedAttributes(no default): only these JSX attributes are checked, beforeignoredAttributes; an object sets them per element.acceptedTags(no default): only these tags are checked, beforeignoredTags;'all'checks every tag, your components included.ignoredAttributesandignoredTags(no default): attributes and tags whose content is not checked.ignore(no default): files to leave out, besides those ofextract.ignore.checkInterpolationParams(defaulttrue): reportst()calls whose values do not match the placeholders.defaultVariables(no default): the variablesinterpolation.defaultVariablesfills in, so they are not reported as missing ('user'covers{{user.name}}).checkConcatenation(default'warn'): strings concatenated with a translation.'error'fails the run,'off'turns it off.checkPunctuationConcatenation(default'off'): punctuation glued onto a translation, such as<Trans>Email</Trans>:.checkTranslationPlaceholders(default'warn'): compares the placeholders ({{name}},$t(key),<0>) of every language with the primary language.checkTransIndices(default'warn'):<Trans>tags of the primary translation that do not match the component's children.baseline(default'i18next-lint-baseline.json'): the filelint --update-baselinewrites.
status
ignoreKeys(no default): keysstatusdoes not report, as patterns likepreservePatterns('*-href','common:empty-table-subtitle').checkIdentical(default'warn'): values identical to the primary language.'error'counts them as untranslated,'off'turns the check off.
types
input(required): the translation files of the primary language, for example['locales/en/*.json'].output(required): thei18next.d.tsto write.resourcesFile(no default): a separate file for the resource types.basePath(no default): keeps folders as part of the namespace; see Namespaces.enableSelector(defaultfalse): types for the selector API;'strict'needs a namespace segment in every path.'optimize'leaves out the type-level processing of your translations, for very large resources; the keys are not changed, so a plural key is given in full (Selector API).indentation(default:extract.indentation).
locize
projectIdandapiKey(best from theLOCIZE_API_KEYenvironment variable),version(default'latest') andcdnType('standard'or'pro'). The commands and their options: Locize commands.
Extending the recommended lint tags and attributes
You can extend the built-in recommended lists for linting by importing and spreading them in your config:
import {
defineConfig,
recommendedAcceptedTags,
recommendedAcceptedAttributes,
} from 'i18next-cli';
export default defineConfig({
locales: ['en', 'de'],
extract: {
input: ['src/**/*.{js,jsx,ts,tsx}'],
output: 'public/locales/{{language}}/{{namespace}}.json',
},
lint: {
acceptedTags: ['my-web-component', ...recommendedAcceptedTags],
acceptedAttributes: ['data-label', ...recommendedAcceptedAttributes]
}
});
Translatable attributes per element
The same prop name can mean different things on different components: label is a button's text but a chart axis's data key. Give acceptedAttributes an object to say per JSX element which props hold text:
import { defineConfig } from 'i18next-cli';
export default defineConfig({
locales: ['en', 'de'],
extract: {
input: ['src/**/*.{js,jsx,ts,tsx}'],
output: 'public/locales/{{language}}/{{namespace}}.json',
acceptedAttributes: {
// label is not text, except where an element adds it back
'*': ['!label'],
Button: ['label'],
PageTitle: ['heading'],
'Select.Option': ['hint']
}
},
lint: {
// lint checks attributes only on the elements acceptedTags lets through
acceptedTags: 'all'
}
});
- A name adds an attribute to the recommended list (
recommendedAcceptedAttributes),!nameremoves it.'*'applies to every element first, then the element's own entry, so an element can add back what'*'removed. - Attribute names are case-insensitive (
helpTextandhelptextare the same attribute). - Element keys are case-sensitive, as in JSX (
Selectis a component,selectthe HTML element), and match the imported name through aliases: afterimport { PageTitle as PT },<PT>uses thePageTitleentry. <Select.Option>uses theSelect.Optionentry when there is one, otherwiseOption.- Set in
extract, the rules apply toinstrumentandlint;lint.acceptedAttributesoverrides them forlintonly.instrumentwraps the values of added attributes (also ones it skips by default, such asname) and leaves the strings of removed ones alone,{...}expressions included; JSX andcount === 1 ? … : …plurals inside a removed attribute are still checked. The array form stays alint-only accept-list. lintchecks attributes only on the elementsacceptedTagslets through, and the recommended tags are HTML tags: for your components useacceptedTags: 'all'or list them.