feat(plugin-i18next)!: replace branded keys with native i18next types

[RedStar071]

🔗 Linked issue

Backport of wolfstar-project/stars-components#30.

Note

This supersedes that PR. @wolfstar/http-framework-i18n — the package it targets — is deprecated
in favour of @wolfstar/plugin-i18next, so upstream #30 can be closed once this lands: the API
changes it makes live here now, and consumers migrate through the plugin's migration guide instead
of upgrading that package.

🧭 Context

stars-components replaced the hand-maintained branded-key helpers (T / FT and the resolve*
functions) in @wolfstar/http-framework-i18n with i18next's own TypeScript support, where keys are
plain strings typed through a CustomTypeOptions augmentation. @wolfstar/plugin-i18next merges
that package with @sapphire/plugin-i18next, so it still shipped the removed API and drifted from
upstream.

📚 Description

Removes the branded-key layer from @wolfstar/plugin-i18next and makes the translator helpers
namespace-aware, matching upstream. Keys are typed by the augmentation generated with
@wolfstar/i18next-type-generator;
without it every helper still accepts plain strings, only untyped.

The generator package itself is not vendored here — it lives in stars-components and is published
to npm, so the README links to it instead. Everything else upstream #30 changed in
http-framework-i18n is covered by this PR, which is what makes that one redundant.

Key changes

Area	Before	After
Key definition	T('commands/ping:success') / FT<{ latency: number }>(...)	The key itself, typed by the generated CustomTypeOptions
Key resolution	resolveKey(target, key, options)	getSupportedLanguageT(target, key, options)
Namespaces	getT(locale), always the default namespace	getT(locale, namespace?) returning TFunction<Ns>
LocalePrefixKey	`commands/${string}:${string}`	`${string}${LocaleSeparator}${string}`, with LocaleSeparator from TypeOptions['nsSeparator']

Removed exports: T, FT, resolveKey, resolveUserKey, TypedT, TypedFT, Value, Values,
Difference.

getSupportedLanguageT and getSupportedUserLanguageT keep the call shape resolveKey and
resolveUserKey had: the key and its options go right after the target, and the bound TFunction is
returned only when no key is passed. A non-default namespace is selected through the ns option.

The TFunction augmentation http-framework-i18n shipped is kept for its metadata half — lng,
lngs, ns and keyPrefix, which i18next assigns on every function getFixedT returns but does
not type — so code reading the language off a bound function migrates untouched. Only the branded
T / FT call signatures are gone.

InternationalizationHandler#getT takes an optional namespace and returns a TFunction<Ns> bound to
it. The cached per-language functions are still used when no namespace is passed, so only an explicit
namespace goes through i18next.getFixedT.

The three test suites that relied on the branded keys were rewritten against the translator helpers,
with new cases covering the namespace-bound functions. The README gained a "Typed keys" section for
the generator and a "Migrating off T / FT / resolve*" section mapping every removed export to
its replacement.

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation change
• Workflow / CI change

Pre-flight Checklist

• I have read the Contributing Guidelines (if applicable)
• My code follows the code style of this project
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have updated the documentation accordingly
• I added a changeset with pnpm changeset (or pnpm changeset add --empty if no release is needed). See .changeset/README.md.

Confidence Score: 5/5

No blocking failure remains in the changed translation behavior.

The focused runtime checks, package test suite, and TypeScript typecheck completed successfully, and no actionable P0 or P1 finding remains.

T-Rex Logs

What T-Rex did

• I ran focused Vitest tests against direct fixed i18next functions and the updated helper functions, and both paths completed with two assertions passing, confirming that the helper forwarding mirrors the i18next behavior; I also ran the full plugin test suite and the TypeScript typecheck, both of which passed.
• I validated semantic parity between baseline and helper-forwarding executions, confirming they produced the same assertions on the tested surface, and noted that the temporary Vitest-discovery test source was copied into the package for discovery and then removed after each run, with the authored source uploaded as validation evidence.

_{Ran code and verified through T-Rex}

_{Reviews (3): Last reviewed commit: "feat(plugin-i18next): declare the metada..." | Re-trigger Greptile}

[pkg-pr-new]

Open in StackBlitz

pnpm add https://pkg.pr.new/@wolfstar/plugin-api@57

pnpm add https://pkg.pr.new/@wolfstar/plugin-i18next@57

pnpm add https://pkg.pr.new/@wolfstar/plugin-subcommands-advanced@57

commit: adbd664