On this page
instrument
Wrap texts written into the code in t() calls, as a first pass you review.
Scans your source code for hardcoded user-facing strings and instruments them with i18next translation calls. This is useful for adding i18next instrumentation to an existing codebase that wasn't built with internationalization in mind.
instrument is a first pass that works from heuristics: it misses some texts and wraps some strings that are not texts. Review every change before you commit it.
npx i18next-cli instrument
Options
--dry-run: Preview changes without writing files to disk: each text with the key it would get, by file--interactive: Prompt for approval of each candidate string--namespace <ns>: Target a specific namespace for extracted keys-q, --quiet: Suppress spinner and output
What it transforms
The instrument command detects five types of transformations:
-
Simple string →
t()call:javascript// Before const msg = 'Welcome back'; // After const msg = t('welcomeBack', 'Welcome back'); -
Template literal (static only) →
t()call:javascript// Before const msg = `Welcome back`; // After const msg = t('welcomeBack', 'Welcome back');With a value inside, the value becomes a placeholder:
`Hello ${name}`becomest('helloName', 'Hello {{name}}', { name }). A literal with no word around its values (`${name}`) stays. -
JSX text → JSX expression with
t():jsx// Before <h1>Welcome back</h1> // After <h1>{t('welcomeBack', 'Welcome back')}</h1> -
JSX mixed content →
<Trans>component:jsx// Before <p>Click <a href="/docs">here</a> to continue</p> // After <p> <Trans i18nKey="clickHereToContinue"> Click <a href="/docs">here</a> to continue </Trans> </p>A link or text component whose only children are text (
<Link to="/docs">here</Link>,<Text.Strong>) and{' '}stay in the sentence too; a button or an icon does not. The key is made from the words, and thei18nKeytakes the quotes the file's JSX attributes use. -
Plurals → one
t()withcount: acount === 1 ? … : …ternary, or a call of a plural helper namedplural,pluralizeorpluralisethat takes(count, one, other), also inside a template literal.#in a form stands for the number, as in ICU:javascript// Before `${n} ${plural(n, 'key', 'keys')} unused` plural(files.length, '# file', '# files') // After t('countKeysUnused', { defaultValue_one: '{{count}} key unused', defaultValue_other: '{{count}} keys unused', count: n }) t('countFiles', { defaultValue_one: '{{count}} file', defaultValue_other: '{{count}} files', count: files.length })Once every call of an imported helper is rewritten, its import goes.
A sentence stays whole around a value: a variable, a property, a string or number formatted from one
({items.join(', ')}, {n.toLocaleString()}, {format.date(d)}), a choice between such values. A placeholder is
named after what it shows: `Last login ${format.date(user.lastLogin)}` becomes 'Last login {{lastLogin}}';
the same expression twice is one placeholder. A key keeps the first words of a long text (at most 40 characters,
no _, which i18next reads as a plural or context suffix), and a key the code uses already is never reused for
another text nor made the parent of nested ones: Tenants next to an existing t('tenants.title') gets tenants2.
What JSX shows is text, a single word too: JSX text (as it renders: lines joined, ' decoded), a
translatable attribute (title, aria-label, data-tip, …), and a string an element renders from an
expression ({busy ? 'saving' : 'saved'}, {name || 'unnamed'}). When one branch of a ternary is text, the
other string branch is too.
Namespace targeting
Use --namespace <ns> to direct extracted keys into a specific namespace. When a non-default namespace is specified:
- React components use
useTranslation('<ns>')with clean keys - Non-component code uses
i18next.t('key', 'default', { ns: '<ns>' }) - In
--interactivemode you are prompted for the target namespace
npx i18next-cli instrument --namespace common
Custom scorer hook
Override the built-in confidence heuristic via extract.instrumentScorer in your config. The function receives each candidate string and its context, and can:
- Return a number (0 to 1) to override the confidence score
- Return
nullto force-skip the candidate - Return
undefinedto fall back to the built-in heuristic
export default defineConfig({
// ...
extract: {
// ...
instrumentScorer: (content, { file, code, beforeContext, afterContext }) => {
// Skip strings that belong to your analytics domain
if (content.startsWith('track_')) return null;
// Boost strings in your UI layer
if (file.includes('/components/')) return 0.95;
// Fall back to built-in detection for everything else
return undefined;
}
}
});
What it skips (by design)
The instrumenter uses confidence heuristics to avoid transforming:
- Test files (
*.test.*,*.spec.*), stories (*.stories.*,*.story.*,*.storybook.*) and the folders__tests__,__mocks__,__fixtures__; other fixture folders go intoextract.ignore - Empty strings and single characters
- Pure numbers and numeric IDs
- URL strings and file paths
- CSS class names and technical identifiers
- Developer-facing error codes (all-caps patterns like
ERROR_NOT_FOUND) console.*calls, everything in them, and variables used only there (a log line built beforehand)- Object keys and computed keys, compared strings and
casevalues; and a string the file also uses as data (compared, anid/key/value/type/code, an entry of anorder/ids/valueslist), everywhere in that file unless an element renders it or it is an attribute's value: a facet'sof()returning'no 2FA'keeps matchingorder: ['2FA', 'no 2FA'] - Prompts for a language model: the functions, variables and properties named like
getSystemPrompt,userPromptoraiAssistantPrompt(a translated prompt changes what the model does) - Analytics event names (
track,trackEvent,logEvent,capture,identify,gtag), event names (emit,on), log and error-report calls (logger.*,Sentry.*),new Error()andRegExparguments (errors are for developers; show users a text of your own), format patterns (dayjs(d).format('DD MMM YYYY')) - Icon ligatures: the content of an element named
…Iconor with amaterial-icons/material-symbolsclass - CSS values (
var(--brand),inset 0 0 5px 1px var(--shadow)), and strings in aclasses/stylevariable - Strings a text is compared with or searched for (
msg.includes('not found'),split,replace, …), selectors (querySelector,closest), attribute and storage names (getAttribute,setItem, …) - camelCase identifiers (
aiReview), rules and key paths (required|min:2), strings without a letter (/), code snippets shown as text (several lines of code or shell commands) - The content of
<code>,<script>and<style>(and ofextract.ignoredTags); inside a sentence they stay part of its<Trans> - HTML attribute values that appear technical (which attributes hold text can be set per element, see Translatable attributes per element); the JSX and functions inside such an attribute (
action={<Button>Change</Button>},onClick={() => notify('Copied')}) are checked as anywhere else - Template literals with no word besides their expressions: ids, paths, keys, language codes and class names
built in code (
`${projectId}-${version}`,`weight_${code}`,`${baseUrl}/api/${id}`,`zh-${country}`); and values of technical properties ({ 'Authorization': `Bearer ${token}` },url,id,type,code,className, …) - Strings already inside
t()calls or<Trans>,<IcuTrans>and their…WithoutContextcomponents (theirvaluestoo), including the project's ownextract.functionsandextract.transComponents - Module-scope strings: anything outside a function body, e.g. a top-level config/registry array:
Ats
export const SETTINGS_SECTIONS = [ { id: 'appearance', label: 'Appearance' }, // left untouched ]t()call there would be evaluated once, when the module is first imported: possibly before i18next is initialized, and never again when the language changes. Move the text into a component, or expose the registry as a hook that callsuseTranslation()internally:tsexport const useSettingsSections = () => { const { t } = useTranslation() return [{ id: 'appearance', label: t('appearance', 'Appearance') }] }
Auto-injection
When transformations are applied, the command automatically:
- Injects
import { useTranslation } from 'react-i18next'in React files (orimport i18next from 'i18next'for non-React files) - Injects
const { t } = useTranslation()into each React function component that contains transformed strings (an arrow component with an expression body,() => <p>…</p>, gets a block for it), unless it has atalready (a prop, or a hook from a module that re-exports it), and addstto the dependencies of auseMemooruseCallbackwhose callback now calls it - Places the imports after the file's import declarations and directives (
'use client'stays first; never inside a string that shows code), and imports no name the file has already, from whatever module - Takes
tfrom a hook call the component makes already, unless a text comes before it:const { i18n } = useTranslation('settings')becomesconst { t, i18n } = useTranslation('settings'), so the new keys go to that namespace; a function that is no component but bindstfrom a translation hook (a custom hook,generateMetadatawithgetT()) uses thatt, noti18next.t() - Detects the project's framework from
package.jsondependencies, dev and peer dependencies included; in a workspace package (npm/yarnworkspaces,pnpm-workspace.yaml) also from the workspace root's - Uses
useTranslation()hook stylet()inside React components, ori18next.t()for utility / non-component code - Generates an
i18n.ts(ori18n.jsfor JS-only projects) initialization file if none exists and the code imports neitheri18nextnorreact-i18nextyet (an app that does is set up somewhere, perhaps in a shared package), pre-configured withi18next-resources-to-backendto lazy-load your translation files via dynamic imports, and with the browser's language (navigator.language, matched against yourlocales); not in a Next.js app, see below - Adds
i18n.changeLanguage()next to a call that sets the user's language:setLanguage(code), or a settings, profile or user call with alanguage/localeproperty (updateSettings({ language: code })). Only where that call is a statement of its own in a block or an arrow function's body, with a plain variable or property as the language (the injected call repeats it), and not for alanguageproperty passed as data (fetchTranslations({ lng })).--dry-runlists every such site; in an app where a language is data (a translation tool's view filter), review them
Next.js apps (next-i18next)
An app with next-i18next (a dependency, or imported), and a Next.js app with no i18next set up at all, gets
next-i18next's calls, by where each file renders. The import graph decides: a file under app/ is a Server
Component unless it says 'use client', a 'use client' file and all it imports are Client Components, a file
under pages/ and all it imports render with the Pages Router (imports resolve relative, through the paths of
tsconfig.json or jsconfig.json and from the project root). A Next.js app with i18next or react-i18next and no
next-i18next keeps react-i18next.
- Server Components:
const { t } = await getT()fromnext-i18next/server(or from the module the app importsgetTfrom, such as its owncreateServerI18nextfile), and the component becomesasync. A<Trans>getst={t} i18n={i18n}and comes fromreact-i18next/TransWithoutContext.generateMetadata()and other async functions getgetT()as well, andexport const metadata = { title: '…' }becomesexport async function generateMetadata () { const { t } = await getT(); return { title: t(…) } }. - Client Components:
const { t } = useT()andTransfromnext-i18next/client. - Pages Router:
useTranslationandTransfromnext-i18next/pages. A page that loads no translations (noserverSideTranslations()in it or in a helper it imports) is named in a warning. - A component that Server and Client Components both render works with neither: its texts stay, named in a
warning, unless it gets
tas a prop (andi18ntoo for a<Trans>), which it then uses. - Left as they are, each named in a warning: texts outside components (next-i18next has no global
t), files no page or layout imports (which side renders them is not known), API routes (route.tsunderapp/,pages/api/), Server Actions and cached functions ('use server','use cache':getT()there needs{ lng }), a Server Component wrapped inmemo()orforwardRef(), and language switches: next-i18next changes the language through the route oruseChangeLanguage(). - No init file: next-i18next sets i18next up itself. When it is not set up yet, the steps are printed (install,
then
i18n.config, proxy and root layout for the App Router,appWithTranslationandserverSideTranslationsfor the Pages Router).
Workflow
- Preview every change:
bash
npx i18next-cli instrument --dry-run - Approve the candidates one by one; use
edit-keyorskipfreely:bashnpx i18next-cli instrument --interactive - Review the changes, run your tests, fix what was missed or wrapped wrongly, and commit.
- Write the keys into the translation files:
bash
npx i18next-cli extract
Limitations
Besides what the warning above says:
- Other plurals: a plural written another way than a
count === 1 ? … : …ternary or aplural,pluralizeorpluralisehelper keeps its form and needs manual cleanup. - Very dynamic strings: strings built from concatenation, template operations or computed values may not be detected correctly.
- Framework-specific patterns: decorators, custom hooks or directives may not be recognized.
Suppressing detection with i18next-instrument-ignore
Both the lint and instrument commands honor an ignore comment so you can skip placeholder or intentionally-untranslated content. It works as a line or block comment, including the JSX {/* ... */} form, and comes in two variants:
| Directive | Scope |
|---|---|
i18next-instrument-ignore |
The entire JSX element that begins on the next line: its opening tag, all nested children, and its closing tag. Falls back to a single line when the next line isn't a JSX element (e.g. a plain t() call). |
i18next-instrument-ignore-next-line |
Only the single line immediately after the directive. |
// Suppress a whole element (including multi-line opening tags and nested
// children)
{/* i18next-instrument-ignore */}
<div
css={css`text-align: center;`}>
Hi, I'm Bob 👋
<p>This nested text is ignored too</p>
</div>
// Suppress just one line
{/* i18next-instrument-ignore-next-line */}
<p>Only this line is ignored</p>
// Also works for t() interpolation warnings in the linter
// i18next-instrument-ignore
const msg = t('Hello {{name}}!', { wrong: 'world' })