> Documentation index: [llms.txt](https://www.i18next.com/llms.txt). Every page is also available as Markdown at its URL plus `.md`.

# 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:

```typescript
// 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:

```typescript
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 `ResourceStatus` is an enum today and widens to `string` in the next release,
> the keys stop resolving and `removeUnusedKeys` (on by default) deletes them, during an
> `npm update` rather 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:
>
> ```typescript
> type 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`, `preservePatterns` keeps 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:

```typescript
// 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:

```javascript
// 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.
