feat: adds new "selector" API by ahrjarrett · Pull Request #2322 · i18next/i18next

ahrjarrett · 2025-06-15T13:02:23Z

Closes #1883
Closes #1972
Closes #2042
Closes #2198
Closes #2204
Closes #2276
Closes #2317
Closes #2320
Closes #2321
Closes i18next/react-i18next#1849
Merge before i18next/react-i18next#1852
Merge before i18next/i18next-gitbook#235
Merge before i18next/react-i18next-gitbook#151
Supersedes #2319

Description

This PR adds a new "selector" API for querying translations.

Feedback on any part of this PR is welcome! Let's make i18next DX even better together 👍

Note

to use this feature, you'll need to add enableSelector: true or enableSelector: 'optimize' to you config
now when you make a query for a translation, you'll pass a selector function as the first argument to t.

Using it looks like this:

Here's an example that shows pluralization being enforced, and the translations being "pruned" when context is provided:

Benefits

Translations are more discoverable

This isn't as much of an issue with small translation sets, but users with larger translation sets can now leverage the native autocompletion API to find the translation they need

JSDoc annotations are preserved

Users now have a way to see any comments that have been made to translations from the call-site, and can even link to other translations

"Go to definition" works like you'd expect

This works even when users change namespaces. Special care was taken when building the types to ensure that all mappings are "homomorphic" (which is just a fancy way of saying that they preserve the link to the original key).
With this feature, users don't need to "track down" translations any more. If they want to see where a translation is defined, they can simply jump to it in their editor. This makes troubleshooting issues easier, and helps users stay in flow.

With enableSelector set to "optimize", users see a ~1,700x improvement in type-level performance

That means i18next is now capable of handling arbitrarily large translation sets
Before/after example using a generated translation set of 30,000 keys, 10 levels deep:

Benchmarks:
- Before: Unable to run benchmarks: running tsc crashes due to the JavaScript heap being out of memory, IDE quits after ~8 seconds with Type instantiation is excessively deep, possibly infinite error
- After (459 instantiations for ~30,000 keys)

With enableSelector set to true, users see a ~300-400% improvement in type-level performance

As in feat: new autocompletion overload #2319, I used @arktype/attest's bench API to measure instantiations, which are strongly correlated to IDE performance
Anecdotally, usage feels noticeably snappier
Benchmarks:
- Before (24,147 instantiations for ~40 keys)
- After (6,558 instantiations for ~40 keys)

No more "doom scrolling"

Before, users with large translation sets (200+ keys) would find themselves needing to scroll through a large list of translations to find the translation they're looking for:

After, users are able to explore their translation dictionaries one level at a time

Implementation

Uses the native Proxy.revocable API under the hood.
The proxy keeps track of property accesses, then converts them into a format that i18next already understands.
The proxy is revoked automatically after the selector is called so that the proxy can be garbage collected.

Migration

To assist with the migration story, I've implemented a codemod that will take care of the migration for users.

For users who'd prefer to handle the migration themselves, here are the changes you'll need to apply when turning on enableSelector:

Namespace changes now happen explicitly, via the options object

Tip

We recommend you use the codemod to automate this step for you

Example:

// BEFORE:
t('ns:a.b.c')

// AFTER:
t($ => $.a.b.c, { ns: 'ns' })

Default value must be explicitly passed via options

Tip

We recommend you use the codemod to automate this step for you

Note

A small type-level change has been made that could impact TypeScript users: when a user provides a default value, the return type of the t function is now a union of the selected type, and the default value's type

Example:

const resources = { a: { b: { c: 'some value' } } } as const

// BEFORE:
const before = t('a.b.c', 'some default value')
//     ^? const before: 'some value'

// AFTER:
const after = t($ => $.a.b.c, { defaultValue: 'some default value' })
//     ^? const after: 'some value' | 'some default value'

Instead of passing an array of keys, users must provide fallback values explicitly
- This can be accomplished by calling t again in defaultValue property of the options object

Tip

We recommend you use the codemod to automate this step for you

Example:

const resources = {
  error: {
    unspecific: "Something went wrong",
    404: "The page was not found"
  } 
} as const

const error = '404'

// BEFORE:
const ex_01 = i18next.t([`error.${error}`, 'error.unspecific'])
console.log(ex_01) // -> "The page was not found"

// AFTER:
const ex_02 = i18next.t($ => $.error[error], { defaultValue: t($ => $.error.unspecific) })
console.log(ex_02) // -> "The page was not found"

Todo

Closing thoughts

The proxy implementation works without a hitch. I fuzz-tested keysFromSelector to build up my own confidence, but I ultimately ripped it out for this PR to keep the cognitive overhead low. Let me know if you'd like me to add that back.

I also added ~200 type-level tests, so I'm fairly confident that there won't be any surprises there.

Checklist

only relevant code is changed (make a diff before you submit the PR)
run tests npm run test
tests are included
commit message and code follows the Developer's Certification of Origin

Checklist (for documentation change)

only relevant documentation part is changed (make a diff before you submit the PR)
motivation/reason is provided
commit message and code follows the Developer's Certification of Origin

…true

refactor: simplifies namespace override implementation

fix: typelevel bug with returnObjects

adrai · 2025-06-15T15:00:40Z

@adrai I just stumbled across this issue in the react-i18next project.

Is that the API you'd prefer (filtering out plural, and just using the version without the plural suffix?

by default, yes

szimek · 2025-08-19T09:49:48Z

Thank you so much for working on this! We're current still on i18next 21.x and react-i18next 11.x, as we had OOM errors with later versions and TS (we've got about 50 namespaces with 5K keys in total), so I'm really looking forward to this.

One question about typing. In some cases we've got a code similar to this defined outside of the component (as it's completely static):

const tabs = [
  {
    label: 'labels.a',
    tooltip: 'tooltips.a',
    route: '/a',
  },
  {
    label: 'labels.b',
    tooltip: 'tooltips.b',
    route: '/b',
  }
] as const

and then use this inside a component, e.g.

const { t: tCommon } = useTranslation('common')

return <Tooltip title={tCommon(tabs[0].tooltip}>
  <Tab label={tCommon(tabs[0].label)}  />
</Tooltip>

How would that work with this new selector API?

ahrjarrett · 2025-08-19T12:02:17Z

@szimek good question. I ran into this in a few places when applying the codemod to the freeCodeCamp repo.

I think the answer will depend on your use case. This is one of the few cases that the codemod can't automate.

You have a few options:

1. See if you can remove the intermediate data structure altogether

function Component({ tab }: { tab: 'a' | 'b' }) {
  const { t } = useTranslation('common')

  return <Tooltip title={t($ => $.tooltips[tab]}>
    {/*                         𐙘_____________𐙘 */}
    <Tab label={t($ => $.labels[tab])}  />
  </Tooltip>
}

Pros: Code is more direct/readable. You also get to delete code, which decreases entropy overall.

Cons: The approach requires you to restructure things a bit, which takes time and makes the migration a bit riskier.

2. Write a helper that turns the path into an accessor

const pathToAccessor = (path: string) => ($: unknown) => path
  .split('.') // ← Note: if you use a non-standard key separator, split on that instead
  .reduce((acc, cur) => (acc as { [x: string]: unknown })[cur], $) as string

const tabs = [
  { label: 'labels.a', tooltip: 'tooltips.a' },
  { label: 'labels.b', tooltip: 'tooltips.b' }
] as const

function Component() {
  const { t } = useTranslation('common')

  return <Tooltip title={t(pathToAccessor(tabs[0].tooltip)}>
    {/*                    𐙘_____________________________𐙘 */}
    <Tab label={t(pathToAccessor(tabs[0].label))}  />
  </Tooltip>
}

Pros: Fast, low-risk.

Cons: It adds a layer of abstraction, and might confuse other devs if they don't understand the purpose.

3. Cast the translation key as `never`

Under the hood, the new API uses a proxy to convert property accesses into a path that i18next already understands.

That means you can technically continue using the path as before, you just have to tell TypeScript to trust you.

const tabs = [
  { label: 'labels.a', tooltip: 'tooltips.a' },
  { label: 'labels.b', tooltip: 'tooltips.b' }
] as const

function Component() {
  const { t } = useTranslation('common')

  return <Tooltip title={t(tabs[0].tooltip as never}>
    {/*                                    𐙘______𐙘 */}
    <Tab label={t(tabs[0].label as never)}  />
  </Tooltip>
}

Pros: Fastest option. Zero risk, since you're only changing the types.

Cons: It's not type-safe, and doesn't feel great.

Which to choose?

If you only use this pattern in a few places, I recommend Option 1 if you can swing it, that way you can finish the migration in one go.

If you use this pattern a lot in your codebase, I recommend you tackle the migration in 2 phases:

Use the codemod, and apply Option 2 or Option 3 as needed
As a separate task, go back and fix the just the places where you used Option 2 or Option 3

ahrjarrett · 2025-08-19T12:13:37Z

@szimek one other approach you could use, that might make more sense for your use case specifically:

const tabs = [
  {
    label: 'a',
    //     𐙘_𐙘 used to be: 'labels.a'
    tooltip: 'a',
    //       𐙘_𐙘 used to be: 'tooltips.a'
    route: '/a',
  },
  {
    label: 'b',
    tooltip: 'b',
    route: '/b',
  }
] as const

function Component() {
  const { t } = useTranslation('common')

  return <Tooltip title={t($ => $.tooltips[tabs[0].tooltip]}>
    {/*                         𐙘_________________________𐙘 */}
    <Tab label={t($ => $.labels[tabs[0].label])}  />
  </Tooltip>
}

szimek · 2025-08-19T15:13:01Z

@ahrjarrett Thank you so much!

marcalexiei · 2025-08-20T09:55:46Z

The migration in my apps is completed.

Summary

Type check times (`enableSelector: true`)

System info

 System:
    OS: macOS 15.6
    CPU: (12) arm64 Apple M2 Max
    Memory: 17.87 GB / 64.00 GB
    Shell: 5.9 - /bin/zsh

Note that timings include an entire app typecheck (not only i18next)

Typescript: 5.8.2

Namespaces	Before	After
2 (200 keys each)	~2.0s	~1.7s
10 (from 100 to 600 keys each)	~3.7s	~3.2s
26 (from 100 to 600 keys each)	~19.8s	~11.4s

Found issues

Note

Opened issues are on the codemod and are not blocking to a release

Codemod

bug(codemod): error when running in an env without pnpm ahrjarrett/i18next-selector#65
bug(codemod): incorrect code generated using namespace together with string interpolation ahrjarrett/i18next-selector#66
feat(codemod): add codemod for <Trans /> component with ns and i18nKey ahrjarrett/i18next-selector#71
bug(codemod): spread in t options is removed ahrjarrett/i18next-selector#80
bug(codemod): empty lines are removed inside jsx ahrjarrett/i18next-selector#81
bug(codemod): Trans - i18nKey with template string are not converted ahrjarrett/i18next-selector#101
bug(codemod): Trans - ternary operator not converted ahrjarrett/i18next-selector#102

Nice to have

React i18next

optimize setting doesn't work - feat: adds support for new "selector" API react-i18next#1852 (comment)
- add test scenario
useTranslation t doesn't error when using namespace NOT provided to useTranslation
- feat: adds support for new "selector" API react-i18next#1852 (comment)
- adds example + comment explaining my expectations about useTranslation's behavior marcalexiei/i18next-playground#1 (review)
<Trans /> i18nKey is typed with only any values - feat: adds support for new "selector" API react-i18next#1852 (comment)

I18next

How to type TFunctionSelector - feat: adds new "selector" API #2322 (comment)

adrai · 2025-08-20T10:13:57Z

Nice 👍
@ahrjarrett @marcalexiei so if for you it's ready to release, I will merge and plan a new ~~major~~ minor bump.
Let me know...

marcalexiei · 2025-08-20T10:54:04Z

From your comment,
I initially understood this should be a minor release:

If this is really just additive, and there is no "backwards compatibility issue", I would suggest we do a minor release... (mentioning a future deprecation)... then on the next major, officially deprecate it, and the next next major, remove the deprecated code (if there is not a major blocker or similar).

If the idea is to go straight to a major release,
I’d suggest at least adding a deprecation notice on the affected exports.

Personally, I’d lean toward a minor release first, so people can try out the feature and share feedback.
Right now, aside from me and @ahrjarrett, I’m not sure how many others have tested it,
since it requires pointing to a specific commit and building manually
(because the dist isn’t versioned across both repos: this one and react-i18next).

adrai · 2025-08-20T10:58:19Z

sorry... intended minor version (probably: v25.4.0)

ahrjarrett · 2025-08-20T12:43:55Z

@adrai Ready once these are finished:

ahrjarrett · 2025-08-20T13:38:04Z

I'm ready to 🚢 it if @marcalexiei is. I re-requested his review so he approve if/when he's ready

adrai · 2025-08-20T14:16:26Z

v25.4.0 has just been released

adrai · 2025-08-20T15:26:16Z

I want to thank you all (but especially you two @ahrjarrett and @marcalexiei ) for the great work on this 👏

I’ve just published a blog post about it * - hopefully this helps more users discover it, give it a try, and share feedback. The more people experiment with it, the better.

* I hope all code snippets in the blog post are correct and the text has not too much errors ;-)

ahrjarrett · 2025-08-20T15:28:35Z

@marcalexiei is the 🐐

ahrjarrett · 2025-08-21T00:27:58Z

Also shout out to @dflourusso, who gave feedback on the original implementation of this feature over a year ago

marcalexiei · 2025-08-21T18:07:37Z

Thanks, @ahrjarrett! However I’d say that title rightfully goes to you:
you not only implemented the feature but also created all the codemods that made the migration process smoother.
Cheers! 🍻

reckter · 2025-08-23T15:31:56Z

I love this!

We have a few cases where we select "the best option" of translation that is available lile this:

<Trans
	i18nKey={chooseKey([
		`a.${it.type}-${it.semanticType}`,
		`a.${it.semanticType}`,
		`a.${it.type}`,
	])}
	t={t}
/>

with chooseKey roughly being:

const chooseKey =  (keys: Array<string>) =>
	keys.find(it =>
		i18n.exists(`${String(prefix)}.${it}`, { ns: namespace }),
	) ?? keys.join(",")

Is there a neat way of doing the same thing with the new api?

i18nKey={$ =>
	$.a[`${it.type}-${it.semanticType}`] ??
	$.a[`${it.semanticType}`] ??
	$.a[`${it.type}`]
}

feels correct, but because ${it.type}-${it.semanticType} might not be there, this has type errors everywhere :/

ahrjarrett · 2025-08-23T16:26:33Z

@reckter good question. If you only do this in a few places, it might be worth keeping the code the same as it was, and casing the string as never (option #3 here).

Under the hood, $ is a Proxy that tracks sequential property access, and uses it to build up the string you used to pass to the t function. It has no real properties of its own, so checking if it contains a particular key won't work.

If you can share the shape of your translation dictionaries I'm happy to help brainstorm a more elegant solution.

giavinh79 · 2025-09-03T07:55:18Z

Hi team, thanks for shipping this feature! Really looking forward to the type-checking performance gains once the migration is finished 🚀

I ran the codemod on a large React monorepo and found out that while it handles most cases (1000+), dynamic keys and template strings are often skipped. Additionally, with stricter type checking in place in general, there are still hundreds of files remaining that require manual effort to resolve their type errors.

It's expected that the codemod can't safely refactor everything especially because in some areas, I've noticed we've adopted some suboptimal patterns with i18n. However in practice this means we need to refactor all these cases ourselves or fall back on less type-safe solutions like as never which can be quite tedious and risky to do all at once.

Is it possible to leverage a more incremental adoption path to reduce migration risk? For example:

Migrating module-by-module instead of all-at-once or
Somehow keeping the legacy API available (in a deprecated state) alongside the new one

Thanks!

ahrjarrett · 2025-09-03T12:50:05Z

@giavinh79 if the project is a monorepo, you might find it easier to migrate one workspace at a time using the approach we discussed in #2344.

tldr; you can create a separate i18next.d.ts per tsconfig.json file, which might be enough to apply the strangler pattern.

If that's not enough to make the migration doable, let me know, happy to keep brainstorming

RohovDmytro · 2025-11-28T16:20:00Z

Wow. Just found this.

Impressive!

gregor-mueller · 2026-04-07T09:29:47Z

The improved DX is very welcome! 👍
Still, I am a bit hesitant to switch as the changes will most probably introduce runtime performance degradation.

Does anyone have benchmarks on how the runtime performance is actually affected?

ahrjarrett added 28 commits June 12, 2025 17:23

poc: selector

76c4fd0

chore: deletes comment

96fe56a

bench: adds benchmark name

aa140c3

chore: a bunch of annoying hacks to remove '@ts-ignore' directive

2d292c3

feat: support returnObjects option

7295519

test: deletes unused test file

e1801e7

docs: adds jsdocs for demo

27216fc

feat: apply returnObjects config from call-site

1b2d3a0

feat: restrict key prefix to be a shallow keep when useSelector is …

d010601

…true

fix: type error

a6687b1

feat: namespace overrides for selector API

8911155

bench: re-measure perf

f1a68b5

refactor: simplifies namespace override implementation

refactor: removes unnecessary extends clause

f6f0922

feat: adds support for defaultValue

6eab959

fix: typelevel bug with returnObjects

test: adds coverage for returnObjects + defaultValue + context case

30d31d1

chore: deletes unused code

4eff97c

feat: adds support for v4 compatibility json plurals

de2165f

test: adds the rest of the selector-custom-types tests, todos

e377c8c

feat: adds support for type-checking interpolations

c9beedc

refactor: simplifies interpolation types

20d1961

chore: cleanup

4954a0c

fix: preserve array types in Selector.FilterKeys

e9e680b

chore: formatting

dedae84

chore: removes comments

74ecc63

optimize: reduce instantiations by 17%

634d310

chore: removes inline comment to move it to PR description

76c79e3

feat: adds support for deeply nested keyPrefix when calling getFixedT

222e703

chore: deletes test key from sample namespace

d6eaa89

This comment was marked as outdated.

Sign in to view

ahrjarrett requested a review from marcalexiei August 20, 2025 12:43

marcalexiei approved these changes Aug 20, 2025

View reviewed changes

adrai merged commit 6c26133 into i18next:master Aug 20, 2025
9 checks passed

ahrjarrett mentioned this pull request Aug 20, 2025

fix: configures i18next to work with the new selector API Tsingis/cars-data#629

Closed

reckter mentioned this pull request Aug 24, 2025

Support enableSelector: "optimize" i18next/i18next-resources-for-ts#6

Closed

adrai mentioned this pull request Oct 5, 2025

Consider a way to annotate dynamic variables in-line i18next/i18next-cli#43

Closed

amarant mentioned this pull request Nov 4, 2025

Selector api : keyFromSelector should return a branded string that t accepts #2364

Closed

seedydocloop mentioned this pull request Jan 8, 2026

Feature request : infer error message as a union of all possible string literals colinhacks/zod#5614

Closed

nabekou29 mentioned this pull request Mar 28, 2026

feat: support i18next Selector API (t($ => $.key)) nabekou29/js-i18n-language-server#10

Closed

Uh oh!

Conversation

ahrjarrett commented Jun 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Benefits

Implementation

Migration

Todo

Closing thoughts

Checklist

Checklist (for documentation change)

Uh oh!

This comment was marked as outdated.

adrai commented Jun 15, 2025

Uh oh!

szimek commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ahrjarrett commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. See if you can remove the intermediate data structure altogether

2. Write a helper that turns the path into an accessor

3. Cast the translation key as never

Which to choose?

Uh oh!

ahrjarrett commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

szimek commented Aug 19, 2025

Uh oh!

marcalexiei commented Aug 20, 2025

Summary

Type check times (enableSelector: true)

Found issues

Codemod

Nice to have

React i18next

I18next

Uh oh!

adrai commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marcalexiei commented Aug 20, 2025

Uh oh!

adrai commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ahrjarrett commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ahrjarrett commented Aug 20, 2025

Uh oh!

Uh oh!

adrai commented Aug 20, 2025

Uh oh!

adrai commented Aug 20, 2025

Uh oh!

ahrjarrett commented Aug 20, 2025

Uh oh!

ahrjarrett commented Aug 21, 2025

Uh oh!

marcalexiei commented Aug 21, 2025

Uh oh!

reckter commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ahrjarrett commented Aug 23, 2025

Uh oh!

giavinh79 commented Sep 3, 2025

Uh oh!

ahrjarrett commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RohovDmytro commented Nov 28, 2025

Uh oh!

gregor-mueller commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

ahrjarrett commented Jun 15, 2025 •

edited

Loading

szimek commented Aug 19, 2025 •

edited

Loading

ahrjarrett commented Aug 19, 2025 •

edited

Loading

3. Cast the translation key as `never`

ahrjarrett commented Aug 19, 2025 •

edited

Loading

Type check times (`enableSelector: true`)

adrai commented Aug 20, 2025 •

edited

Loading

adrai commented Aug 20, 2025 •

edited

Loading

ahrjarrett commented Aug 20, 2025 •

edited

Loading

reckter commented Aug 23, 2025 •

edited

Loading

ahrjarrett commented Sep 3, 2025 •

edited

Loading