npm install @wolfstar/plugin-i18next

pnpm add @wolfstar/plugin-i18next

yarn add @wolfstar/plugin-i18next

bun add @wolfstar/plugin-i18next

npm

Source

Coming from @wolfstar/http-framework-i18n? Follow the migration guide.

@wolfstar/plugin-i18next

i18next-powered internationalization for HTTP interactions.

Description

Plugin for @wolfstar/http-framework that adds an internationalization layer powered by i18next and @wolfstar/i18next-backend. It merges two upstream implementations:

@wolfstar/http-framework-i18n (now removed) — the HTTP-interaction helpers (getSupportedLanguageT, applyLocalizedBuilder, localized builders).
@sapphire/plugin-i18next — the plugin architecture (container.i18n, InternationalizationHandler, custom fetchLanguage, formatters, HMR).

Interactions arrive over HTTP as raw payloads, so every helper operates on discord-api-types structures instead of discord.js class instances.

Installation

pnpm add @wolfstar/http-framework @wolfstar/plugin-i18next

Requires Node.js >=22.22.0.

Usage

Import the register entrypoint before creating the client:

import '@wolfstar/plugin-i18next/register';
import { Client } from '@wolfstar/http-framework';

const client = new Client({
	i18n: {
		// Defaults to `<root>/languages`:
		defaultLanguageDirectory: new URL('languages', import.meta.url).pathname,
		defaultName: 'en-US',
		defaultMissingKey: 'default:default',
		formatters: [
			{ name: 'uppercase', format: (value) => value.toUpperCase() },
			{ name: 'lowercase', format: (value) => value.toLowerCase() }
		]
	}
});

The plugin registers three hooks:

Hook	What it does
`preGenericsInitialization`	Creates the `InternationalizationHandler` and assigns it to `container.i18n`.
`preLoad`	Awaits `container.i18n.init()` before the stores load, so command builders can be localized.
`postListen`	Starts the chokidar watcher when `i18n.hmr.enabled` is `true`.

Activating with `modules`

On framework 6.1 and later, list the ./module entry in modules in stars.config instead of importing register. It needs the optional @wolfstar/kit peer dependency, at ^0.2.0 || ^0.3.0.

// stars.config.ts
import { defineConfig } from '@wolfstar/http-framework/config';
import '@wolfstar/plugin-i18next/module';

export default defineConfig({
	modules: ['@wolfstar/plugin-i18next/module'],
	i18n: { defaultLanguageDirectory: './languages' }
});

The module reads its options from the i18n key of stars.config. The [specifier, options] tuple of modules still works. Its options are merged over the i18n key, so they win. The optional @wolfstar/schema peer dependency types the i18n key in defineConfig. TypeScript only loads that type once the module is imported, so import @wolfstar/plugin-i18next/module in stars.config.ts. Module options must be JSON-serialisable. Set fetchLanguage and functions in hmr.options through ClientOptions.i18n, which is shallowly merged over the module options. Because the merge is shallow, an hmr object set there replaces the module’s whole hmr object, so include enabled: true in it. Without the stars CLI, pass the ./plugin definePlugin factory to the plugins client option:

import i18nPlugin from '@wolfstar/plugin-i18next/plugin';

const client = new Client({ plugins: [i18nPlugin({ defaultName: 'en-US' })] });

Use only one of the module, the ./plugin factory, and register. Combining them installs the plugin’s hooks twice.

Languages directory

languages/
├── en-US/
│   ├── default.json
│   └── commands/
│       └── ping.json
└── es-ES/
    ├── default.json
    └── commands/
        └── ping.json

Every top-level directory is a language, every nested .json file is a namespace (commands/ping).

Typed keys

Keys are typed through i18next’s own CustomTypeOptions augmentation. Generate it from the locale files with @wolfstar/i18next-type-generator, listed as an optional peer dependency — nothing at runtime depends on it, only the generated types consumers opt into:

pnpm add -D @wolfstar/i18next-type-generator
i18next-type-generator ./languages/en-US/ ./src/@types/i18next.d.ts

The generator only emits CustomTypeOptions.resources. If defaultNS is set to anything other than i18next’s own 'translation' default — this plugin’s defaultLanguageDirectory layout usually implies 'default' — declare it separately, or every helper’s default namespace stops satisfying i18next’s Namespace type:

declare module 'i18next' {
	interface CustomTypeOptions {
		defaultNS: 'default';
	}
}

See i18next’s TypeScript guide for the other options the augmentation accepts. Without any of this every helper still accepts plain strings, only untyped.

Consumption

import { getSupportedLanguageName, getSupportedLanguageT, getSupportedUserLanguageName, getSupportedUserLanguageT } from '@wolfstar/plugin-i18next';

// The guild's language, falling back to the user's one in DMs:
const guildLanguage = getSupportedLanguageName(interaction);

// The user's language:
const userLanguage = getSupportedUserLanguageName(interaction);

// Synchronous, resolved straight from the interaction payload:
const content = getSupportedLanguageT(interaction, 'commands/ping:success');
const userContent = getSupportedUserLanguageT(interaction, 'commands/ping:successWithLatency', {
	latency: 42
});

// Omitting the key returns the bound `TFunction` instead, for when several keys share a language:
const t = getSupportedUserLanguageT(interaction);
const name = t('commands/ping:name');

// Bound functions carry the language they were fixed to, as they did in `@wolfstar/http-framework-i18n`:
t.lng; // 'es-ES

getSupported*T helpers are synchronous and only read the locales carried by the interaction. Use the asynchronous fetch* helpers when the language comes from somewhere else — they go through container.i18n.fetchLanguage:

import { container } from '@wolfstar/http-framework';
import { fetchKey, fetchLanguage, fetchT } from '@wolfstar/plugin-i18next';

container.i18n.fetchLanguage = async (context) => {
	if (!context.guildId) return null;
	const guild = await database.getGuild(context.guildId);
	return guild?.language ?? null;
};

const language = await fetchLanguage(interaction);
const t = await fetchT(interaction);
const content = await fetchKey(interaction, 'commands/ping:success');

Targets

Every helper accepts any of four raw payloads, told apart structurally — the framework never has discord.js class instances to check with instanceof:

Target	Recognized by	Locale it carries
`Interaction`	`locale`	`locale` and `guild_locale`
`MessageTarget`	`channel_id`	none
`ChannelTarget`	`type`	none
`GuildTarget`	anything else	`preferred_locale`

APIInteraction, APIMessage, APIChannel and APIGuild all satisfy the matching target, so payloads can be passed straight through:

import { getSupportedLanguageName, getSupportedLanguageT } from '@wolfstar/plugin-i18next';

// A guild resolves through its `preferred_locale`:
const guild = await container.rest.get(Routes.guild(guildId));
const language = getSupportedLanguageName(guild);
const content = getSupportedLanguageT(guild, 'commands/ping:success');

Channels and messages carry no locale of their own, so the synchronous helpers fall back to defaultName for them. Use the asynchronous fetch* helpers instead: the hook receives the target’s guildId, channelId and userId, which is enough to look the language up.

container.i18n.fetchLanguage = async ({ guildId }) => (guildId ? ((await database.getGuild(guildId))?.language ?? null) : null);

const content = await fetchKey(message, 'commands/ping:success');

Localizing command builders

import { RegisterCommand } from '@wolfstar/http-framework';
import { applyLocalizedBuilder, createLocalizedChoice } from '@wolfstar/plugin-i18next';

@RegisterCommand((builder) =>
	applyLocalizedBuilder(builder, 'commands/ping:name').addStringOption((option) =>
		applyLocalizedBuilder(option, 'commands/ping:mode')
			.setRequired(true)
			.setChoices(
				createLocalizedChoice('commands/ping:modeFast', { value: 'fast' }),
				createLocalizedChoice('commands/ping:modeSlow', { value: 'slow' })
			)
	)
)
export class UserCommand extends Command {}

Passing a single root key resolves <root>Name and <root>Description; passing two keys uses them verbatim.

[!IMPORTANT] Builder localization reads the loaded resources, so it may only run after the preLoad hook has initialized the handler. The plugin already guarantees this ordering for pieces loaded by Client#load.

Hot module replacement

const client = new Client({
	i18n: {
		hmr: { enabled: true }
	}
});

When enabled, the languages directory is watched and container.i18n.reloadResources() runs on every addition, change or deletion — including new locale directories and new namespace files, which are registered on i18next and become usable without a restart. ignoreInitial defaults to true so the files already on disk do not each trigger a reload on startup; pass hmr.options to override it or any other chokidar option. The watcher is exposed as I18nextPlugin.watcher, so it can be closed on shutdown:

import { I18nextPlugin } from '@wolfstar/plugin-i18next/register';

await I18nextPlugin.watcher?.close();

Options

Option	Type	Description
`defaultName`	`string`	The locale used when none of an interaction’s locales is loaded. Defaults to `'en-US'`.
`defaultLanguageDirectory`	`string`	Where to look for languages. Defaults to `<root>/languages`.
`defaultMissingKey`	`string`	The key used to render missing keys, e.g. `'default:default'`.
`defaultNS`	`string`	The namespace prefixed to keys that don’t specify one. Defaults to `'default'`.
`backend`	`Backend.Options`	Extra `@wolfstar/i18next-backend` paths.
`i18next`	`InitOptions \| DynamicOptions`	Raw options forwarded to `i18next.init`.
`formatters`	`I18nextFormatter[]`	Formatters registered on `i18next.services.formatter`.
`hmr`	`HMROptions`	Chokidar-based hot reloading of the languages directory.
`fetchLanguage`	`(context) => Awaitable<string \| null>`	Custom language resolution, used by the `fetch*` helpers.

Migrating from `@wolfstar/http-framework-i18n`

@wolfstar/http-framework-i18n has been removed and is no longer maintained. This plugin replaces it. The upstream changes are documented in wolfstar-project/stars-components#30; the short version:

pnpm remove @wolfstar/http-framework-i18n
pnpm add @wolfstar/plugin-i18next

-import { addFormatters, init, load } from "@wolfstar/http-framework-i18n";
+import "@wolfstar/plugin-i18next/register";
 import { Client } from "@wolfstar/http-framework";
+import { fileURLToPath } from "node:url";

-await load(new URL("locales", import.meta.url));
-addFormatters({ name: "uppercase", format: (value) => value.toUpperCase() });
-await init();
-
-const client = new Client();
+const client = new Client({
+  i18n: {
+    defaultLanguageDirectory: fileURLToPath(new URL("languages", import.meta.url)),
+    formatters: [{ name: "uppercase", format: (value) => value.toUpperCase() }],
+  },
+});

getSupportedLanguageName, getSupportedUserLanguageName, getSupportedLanguageT, getSupportedUserLanguageT (which now also take the key and its options directly, like resolveKey did), supportedLanguages, isSupportedDiscordLocale, getLocalizedData, applyNameLocalizedBuilder, applyDescriptionLocalizedBuilder, applyLocalizedBuilder and createSelectMenuChoiceName keep the same names and signatures — only the module specifier changes.

Removed upstream	Replacement here
`load(directory)`	`defaultLanguageDirectory` option
`init(options)`	The `preLoad` hook; raw options go to the `i18next` option
`addFormatters(...formatters)`	`formatters` option
`getT(locale, namespace?)`	`container.i18n.getT(locale, namespace?)`
`loadedLocales`	`container.i18n.languages`
`loadedNamespaces`	`container.i18n.namespaces`
`loadedPaths`	Derived from `defaultLanguageDirectory`; extra paths via the `backend` option
`loadedFormatters`	`container.i18n.options.formatters`
`Formatter`	`I18nextFormatter`

T, FT, resolveKey and resolveUserKey were removed upstream in wolfstar-project/stars-components#30 and are gone here too — see Migrating off T / FT / resolve* below. Other differences: @wolfstar/http-framework@^3.1.0 is now a peer dependency, i18next moves from ^22 to ^25, and the locales directory defaults to <root>/languages instead of an explicit path passed to load() — the layout itself is unchanged.

Migrating off `T` / `FT` / `resolve*`

The branded-key helpers were replaced by i18next’s native TypeScript support, so keys are plain strings typed by the CustomTypeOptions augmentation @wolfstar/i18next-type-generator emits.

-import { FT, T } from "@wolfstar/plugin-i18next";
-
-export const Success = T("commands/ping:success");
-export const SuccessWithLatency = FT<{ latency: number }>("commands/ping:successWithLatency");

Removed	Replacement
`T(key)` / `FT<Args>(key)`	The key itself, typed by the generated augmentation
`resolveKey(target, key, options)`	`getSupportedLanguageT(target, key, options)`
`resolveUserKey(target, key, options)`	`getSupportedUserLanguageT(target, key, options)`
`TypedT` / `TypedFT`	`ParseKeys` from `i18next`
`Value` / `Values` / `Difference`	Interpolation options are inferred from the locale files

TFunction#lng (along with lngs, ns and keyPrefix) is still declared, so code reading the language off a bound function keeps working — i18next assigns them on every function getFixedT returns but does not type them. LocalePrefixKey is no longer hardcoded to commands/<file>:<key>: it is now `${string}${LocaleSeparator}${string}`, with LocaleSeparator read from i18next’s TypeOptions["nsSeparator"].

-const content = resolveKey(interaction, Success);
-const userContent = resolveUserKey(interaction, SuccessWithLatency, { latency: 42 });
+const content = getSupportedLanguageT(interaction, "commands/ping:success");
+const userContent = getSupportedUserLanguageT(
+  interaction,
+  "commands/ping:successWithLatency",
+  { latency: 42 },
+);

Credits

Adapted from @wolfstar/http-framework-i18n and @sapphire/plugin-i18next (MIT).

Infrastructure

Shared pieces

Platform helpers

Plugins

@wolfstar/plugin-i18next

npm

Source

@wolfstar/plugin-i18next

Description

Installation

Usage

Activating with `modules`

Languages directory

Typed keys

Consumption

Targets

Localizing command builders

Hot module replacement

Options

Migrating from `@wolfstar/http-framework-i18n`

Migrating off `T` / `FT` / `resolve*`

Credits

npm

Source

​@wolfstar/plugin-i18next

​Description

​Installation

​Usage

​Activating with modules

​Languages directory

​Typed keys

​Consumption

​Targets

​Localizing command builders

​Hot module replacement

​Options

​Migrating from @wolfstar/http-framework-i18n

​Migrating off T / FT / resolve*

​Credits

@wolfstar/plugin-i18next

Description

Installation

Usage

Activating with `modules`

Languages directory

Typed keys

Consumption

Targets

Localizing command builders

Hot module replacement

Options

Migrating from `@wolfstar/http-framework-i18n`

Migrating off `T` / `FT` / `resolve*`

Credits