Dynamic keys
Keys built at run time: which ones the extractor finds by itself, and how to tell it about the rest.
Many "dynamic" keys need no configuration: the extractor resolves finite dynamic keys with the TypeScript types and expands every possible variant:
// Template literals with unions / ternaries / nullish coalescing:
// -> state.done.title + state.notDone.title
t(`state.${isDone ? 'done' : 'notDone'}.title`)
type Status = 'active' | 'inactive'
declare const status: Status
t(`status.${status}`) // -> status.active + status.inactive
// `as const` maps and arrays (also when imported from another file):
const KEYS = ['a', 'b'] as const
KEYS.map((k) => t(`item.${k}`)) // -> item.a + item.b
const MAP = { ok: 'result.ok', err: 'result.err' } as const
t(MAP[someCondition ? 'ok' : 'err']) // -> result.ok + result.err
// Helper-function return types and `satisfies`-constrained values
Resolution is name-based across every scanned file, including through renaming
imports (import { ResourceStatus as Status } from './types'). Types declared by
a dependency work too, but only if you let the scan reach them. node_modules is
skipped unless an input pattern says otherwise:
export default defineConfig({
extract: {
input: [
'src/**/*.{ts,tsx}',
// declaration file scanned for its types; a `.d.ts` holds no keys to
// extract
'node_modules/@acme/api-sdk/dist/*.d.ts',
],
}
});
The same applies to a package that ships translatable sources: glob its files and their keys are extracted like your own.
Careful with dependency types: keys derived from them change when the dependency does. If
ResourceStatusis an enum today and widens tostringin the next release, the keys stop resolving andremoveUnusedKeys(on by default) deletes them, during annpm updaterather than in a diff you wrote. Consider copying the type into your own source instead and guarding it against drift, so a mismatch fails typecheck in CI rather than silently emptying a locale file:typescripttype Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false; type Assert<T extends true> = T; // drop the `${}` when the upstream type is a string union rather than an enum type _driftGuard = Assert<Equals<LocalStatus, `${ResourceStatus}`>>;If you do read from
node_modules,preservePatternskeeps the already-translated entries alive even when resolution stops producing them.
Only keys that are truly runtime-dynamic (e.g. built from API data) cannot
be statically resolved by any tool. For those, use preservePatterns to keep
the existing entries in your translation files:
// Code like this:
const key = `user.${role}.permission`; // role comes from the server
t(key);
// With this config:
export default defineConfig({
extract: {
preservePatterns: ['user.*.permission']
}
});
// Will preserve existing keys matching the pattern
Comment-based extraction
Extract keys from comments for documentation or edge cases:
// t('welcome.message', 'Welcome to our app!')
// t('user.greeting', { defaultValue: 'Hello!', ns: 'common' })
A commented template literal cannot name its keys, so it is not extracted. Instead it keeps the
existing keys it matches, even with removeUnusedKeys: // t(`QUARTER.${q}`) keeps QUARTER.1,
QUARTER.2 and so on, while code can still add new QUARTER.* keys. Unlike preservePatterns, it
does not stop matching keys from being extracted.