Internationalization API

Location: src/lib/i18n.ts

Internationalization (i18n) helpers for multi-language support.

Supported Languages

import { AVAILABLE_LANGUAGES } from '#lib/i18n.js';

// [
//   { code: 'en-US', name: 'English (US)', flag: '🇺🇸' },
//   { code: 'es-ES', name: 'Español', flag: '🇪🇸' },
//   { code: 'fr-FR', name: 'Français', flag: '🇫🇷' },
// ]

Translation Files

Translation files are located in languages/:

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

Example translation file (languages/en-US/commands/ping.json):

{
  "description": "Check the bot latency",
  "response": "Pong! Latency: {{latency}}ms"
}

Functions

getGuildLanguage(guildId)

Get the language setting for a guild.

import { getGuildLanguage } from '#lib/i18n.js';

const language = await getGuildLanguage(guild.id);
// 'en-US' (default) or the guild's configured language

Parameter	Type	Description
guildId	string	Discord guild ID

Returns: Promise<string> - Language code (falls back to 'en-US')

---

getLanguageName(code)

Get the display name for a language code.

import { getLanguageName } from '#lib/i18n.js';

getLanguageName('en-US'); // '🇺🇸 English (US)'
getLanguageName('es-ES'); // '🇪🇸 Español'
getLanguageName('unknown'); // 'unknown'

Parameter	Type	Description
code	string	Language code

Returns: string - Display name with flag emoji

---

isValidLanguage(code)

Check if a language code is supported.

import { isValidLanguage } from '#lib/i18n.js';

isValidLanguage('en-US'); // true
isValidLanguage('de-DE'); // false

Parameter	Type	Description
code	string	Language code to check

Returns: boolean

---

resolveKeyForInteraction(interaction, key, values?)

Resolve a translation key for an interaction.

import { resolveKeyForInteraction } from '#lib/i18n.js';

const message = await resolveKeyForInteraction(
  interaction,
  'commands/ping:response',
  { latency: client.ws.ping }
);
// 'Pong! Latency: 50ms'

Parameter	Type	Description
interaction	Interaction	Discord interaction
key	string	Translation key (namespace:key format)
values	Record<string, unknown>?	Interpolation values

Returns: Promise<string>

---

resolveKeyForMessage(message, key, values?)

Resolve a translation key for a message.

import { resolveKeyForMessage } from '#lib/i18n.js';

const content = await resolveKeyForMessage(
  message,
  'commands/help:title'
);

Parameter	Type	Description
message	Message	Discord message
key	string	Translation key
values	Record<string, unknown>?	Interpolation values

Returns: Promise<string>

---

Using i18n in Commands

Basic Usage

import { Command } from '@sapphire/framework';
import { resolveKeyForInteraction } from '#lib/i18n.js';

export class PingCommand extends Command {
  public async chatInputRun(interaction: Command.ChatInputCommandInteraction) {
    const latency = this.container.client.ws.ping;

    const response = await resolveKeyForInteraction(
      interaction,
      'commands/ping:response',
      { latency }
    );

    return interaction.reply(response);
  }
}

With Sapphire's resolveKey

You can also use Sapphire's built-in resolveKey:

import { resolveKey } from '@sapphire/plugin-i18next';

const message = await resolveKey(interaction, 'commands/ping:response', {
  latency: client.ws.ping
});

Command Descriptions

Use i18n for command descriptions:

import { ApplyOptions } from '@sapphire/decorators';
import { Command } from '@sapphire/framework';

@ApplyOptions<Command.Options>({
  name: 'ping',
  description: 'commands/ping:description',
})
export class PingCommand extends Command {
  // ...
}

---

Adding a New Language

1. Create a new directory in languages/:

   languages/de-DE/

2. Add translation files matching the structure:

   languages/de-DE/commands/ping.json

3. Add the language to AVAILABLE_LANGUAGES in src/lib/i18n.ts:

   export const AVAILABLE_LANGUAGES = [
     { code: 'en-US', name: 'English (US)', flag: '🇺🇸' },
     { code: 'es-ES', name: 'Español', flag: '🇪🇸' },
     { code: 'fr-FR', name: 'Français', flag: '🇫🇷' },
     { code: 'de-DE', name: 'Deutsch', flag: '🇩🇪' }, // New
   ] as const;

---

Interpolation

Use syntax for dynamic values:

{
  "welcome": "Welcome {{username}} to {{server}}!",
  "level_up": "Congratulations! You reached level {{level}}."
}

await resolveKeyForInteraction(interaction, 'messages:welcome', {
  username: user.username,
  server: guild.name
});

---

Related

• Database API - Guild language storage
• Commands - Using i18n in commands