@sapphire/plugin-i18next

Plugin for @sapphire/framework to support i18next based internationalization.

Description

An implementation of i18next's filesystem backend for Sapphire. It allows you to use a JSON-based languages directory to add internationalization for your bot using SapphireClient's fetchLanguage hook and a custom message extension, adding features such as sendTranslated and resolveKey.

Features

• Fully ready for TypeScript!
• Includes ESM ready entrypoint
• Framework agnostic
• Includes convenience register for discord.js

Installation

@sapphire/plugin-i18next depends on the following packages. Be sure to install these along with this package!

• @sapphire/framework
• discord.js

You can use the following command to install this package, or replace npm install with your package manager of choice.

npm install @sapphire/plugin-i18next @sapphire/framework discord.js

---

Usage

This registers the methods and options necessary for message translations in the Sapphire client.

// Main bot file
// Be sure to register the plugin before instantiating the client.
import '@sapphire/plugin-i18next/register';

The basic structure of a translation file is as follows:

// languages/en-US/commands/ping.json
{
	"success": "Pong!",
	"success_with_args": "Pong! Took me {{latency}}ms to reply"
}

The resolveKey function can be used anywhere to get translated text by its key. In this example, it is used in a method to send a message.

import { resolveKey } from '@sapphire/plugin-i18next';
import { Command } from '@sapphire/framework';
import type { Message } from 'discord.js';

export class PingCommand extends Command {
	public constructor(context: Command.LoaderContext, options: Command.Options) {
		super(context, {
			...options,
			description: 'ping pong'
		});
	}

	public async messageRun(message: Message) {
		await message.channel.send(await resolveKey('commands/ping:success'));
	}
}

sendLocalized will send translated text resolved from a key to a specified channel.

import { sendLocalized } from '@sapphire/plugin-i18next';
import { Command } from '@sapphire/framework';

import type { Message } from 'discord.js';

export class PingCommand extends Command {
	public constructor(context: Command.LoaderContext, options: Command.Options) {
		super(context, {
			...options,
			description: 'ping pong'
		});
	}

	public async messageRun(message: Message) {
		await sendLocalized(message, 'commands/ping:success');
	}
}

editLocalized edits a message, replacing its content with translated text resolved from its key.

import { editLocalized } from '@sapphire/plugin-i18next';
import { Command } from '@sapphire/framework';

import type { Message } from 'discord.js';

export class PingCommand extends Command {
	public constructor(context: Command.LoaderContext, options: Command.Options) {
		super(context, {
			...options,
			description: 'ping pong'
		});
	}

	public async messageRun(message: Message) {
		await editLocalized(message, 'commands/ping:success_args', { latency: ws.ping });
	}
}

fetchLanguage returns the guild-specific language that the client is using.

import { fetchLanguage } from '@sapphire/plugin-i18next';
import { Command } from '@sapphire/framework';

import type { Message } from 'discord.js';

export class PingCommand extends Command {
	public constructor(context: Command.LoaderContext, options: Command.Options) {
		super(context, {
			...options,
			description: 'ping pong'
		});
	}

	public async messageRun(message: Message) {
		return message.channel.send(await fetchLanguage(message));
		// ===> en-US
	}
}

Buy us some doughnuts

Sapphire Community is and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance!

We accept donations through Open Collective, Ko-fi, Paypal, Patreon and GitHub Sponsorships. You can use the buttons below to donate through your method of choice.

Donate With	Address
Open Collective	Click Here
Ko-fi	Click Here
Patreon	Click Here
PayPal	Click Here

Contributors

Please make sure to read the Contributing Guide before making a pull request.

Thank you to all the people who already contributed to Sapphire!

Classes

Class	Description
InternationalizationHandler	A generalized class for handling i18next JSON files and their discovery.

Interfaces

Interface	Description
$Dictionary	This is a re-exported type from i18next. It is essentially an object of key-value pairs, where the key is a string and the value is any.
BuilderWithDescription	-
BuilderWithName	-
HMROptions	Configure whether to use Hot-Module-Replacement (HMR) for your i18next resources using these options. The minimum config to enable HMR is to set enabled to true. Any other properties are optional.
I18nextFormatters	-
I18nextNamedCachedFormatter	Represents a cached formatter that is added to i18next with i18next.services.formatter.addCached.
I18nextNamedFormatter	Represents a cached formatter that is added to i18next with i18next.services.formatter.add.
InternationalizationClientOptions	-
InternationalizationContext	Context for InternationalizationHandler.fetchLanguage functions. This context enables implementation of per-guild, per-channel, and per-user localization.
InternationalizationOptions	The options used in InternationalizationHandler.
LocalizedData	-
TFunction	-

Type Aliases

Type Alias	Description
$NoInfer	This is a re-exported type from i18next.
$SpecialObject	This is a re-exported type from i18next. It is the returned type from resolveKey when returnObjects is true in the options.
BuilderWithNameAndDescription	-
ChannelTarget	-
DiscordChannel	-
DynamicOptions	Used to dynamically add options based on found languages in InternationalizationHandler#init.
I18nextFormatter	Represents a formatter that is added to i18next with i18next.services.formatter.add or i18next.services.formatter.addCached, depending on the cached property.
Target	-
TextBasedDiscordChannel	-
TOptions	-

Variables

Variable	Description
i18next	-
version	The @sapphire/plugin-i18next version that you are currently using. An example use of this is showing it of in a bot information command.

Functions

Function	Description
applyDescriptionLocalizedBuilder	Applies the localized descriptions on the builder, calling setDescription and setDescriptionLocalizations.
applyLocalizedBuilder	Applies the localized names and descriptions on the builder, calling applyNameLocalizedBuilder and applyDescriptionLocalizedBuilder.
applyNameLocalizedBuilder	Applies the localized names on the builder, calling setName and setNameLocalizations.
createLocalizedChoice	Constructs an object that can be passed into setChoices for String or Number option with localized names.
fetchLanguage	Retrieves the language name for a specific target, using InternationalizationHandler.fetchLanguage. If InternationalizationHandler.fetchLanguage is not defined or this function returns a nullish value, then there will be a series of fallback attempts in the following descending order: 1. Returns Guild.preferredLocale. 2. Returns InternationalizationOptions.defaultName if no guild was provided. 3. Returns 'en-US' if nothing else was found.
fetchT	Retrieves the language-assigned function from i18next designated to a target's preferred language code.
getLocalizedData	Gets the value and the localizations from a language key.
resolveKey	Resolves a key and its parameters.