Skip to content

Commit 525c877

Browse files
twlitetwlite
committed
docs: document localization
1 parent 7b54bca commit 525c877

File tree

11 files changed

+903
-157
lines changed

11 files changed

+903
-157
lines changed

‎apps/test-bot/src/app/locales/en-US/messageCreate.event.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"say-hi": "Hi!"
3-
}
2+
"say-hi": "Hi!"
3+
}

‎apps/test-bot/src/app/locales/fr/messageCreate.event.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"say-hi": "Salut!"
3-
}
2+
"say-hi": "Salut!"
3+
}

‎apps/website/docs/guide/06-plugins/official-plugins/02-i18n.mdx‎

Lines changed: 1 addition & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -10,145 +10,4 @@ import TabItem from '@theme/TabItem';
1010

1111
The i18n plugin integrates i18next into CommandKit, allowing you to internationalize your Discord bot and translate your commands, responses, and other content into multiple languages.
1212

13-
## Installation
14-
15-
<Tabs>
16-
<TabItem value="npm" label="npm">
17-
18-
```bash
19-
npm install @commandkit/i18n
20-
```
21-
22-
</TabItem>
23-
<TabItem value="yarn" label="yarn">
24-
25-
```bash
26-
yarn add @commandkit/i18n
27-
```
28-
29-
</TabItem>
30-
<TabItem value="pnpm" label="pnpm">
31-
32-
```bash
33-
pnpm add @commandkit/i18n
34-
```
35-
36-
</TabItem>
37-
</Tabs>
38-
39-
## Basic Setup
40-
41-
Add the i18n plugin to your CommandKit configuration:
42-
43-
```ts
44-
import { defineConfig } from 'commandkit';
45-
import { i18n } from '@commandkit/i18n';
46-
47-
export default defineConfig({
48-
plugins: [i18n()],
49-
});
50-
```
51-
52-
## Advanced Configuration
53-
54-
You can customize the i18n plugin by passing options to it:
55-
56-
```ts
57-
import { defineConfig } from 'commandkit';
58-
import { i18n } from '@commandkit/i18n';
59-
// Import any i18next plugins you want to use
60-
import someI18nextPlugin from 'some-i18next-plugin';
61-
62-
export default defineConfig({
63-
plugins: [
64-
i18n({
65-
plugins: [someI18nextPlugin],
66-
// Add other i18next configuration options as needed
67-
}),
68-
],
69-
});
70-
```
71-
72-
## Translation Files Structure
73-
74-
Create a `locales` directory inside your `src/app` folder with subdirectories for each language. The directory structure should look like this:
75-
76-
```
77-
src
78-
└── app
79-
├── locales
80-
│ ├── en-US
81-
│ │ └── ping.json
82-
│ └── fr
83-
│ └── ping.json
84-
└── commands
85-
└── ping.ts
86-
```
87-
88-
## Translation File Format
89-
90-
Translation files should be named after the command they translate. For example, the translation for a `ping` command would be in `ping.json`.
91-
92-
If your translation file contains the special `$command` key, it will be used to localize the command name, description, and options:
93-
94-
```json
95-
{
96-
"$command": {
97-
"name": "Ping",
98-
"description": "Ping the server",
99-
"options": [
100-
{
101-
"name": "database",
102-
"description": "Ping the database"
103-
}
104-
]
105-
},
106-
"response": "Pong! The latency is {{latency}}ms"
107-
}
108-
```
109-
110-
The `$command` key is used to localize the command's metadata for Discord, while other keys are available for localizing command responses.
111-
112-
## Using Translations in Commands
113-
114-
Use the `locale()` function in your command context to access translations:
115-
116-
```ts
117-
export const chatInput: ChatInputCommand = async (ctx) => {
118-
// Get translation function and i18next instance for the current guild's locale
119-
const { t, i18n } = ctx.locale();
120-
121-
// Use the translation function with variables
122-
ctx.interaction.reply({
123-
content: t('response', { latency: ctx.client.ws.ping }),
124-
ephemeral: true,
125-
});
126-
};
127-
```
128-
129-
You can also specify a particular locale:
130-
131-
```ts
132-
// Use French locale explicitly
133-
const { t } = ctx.locale('fr');
134-
```
135-
136-
## Using Translations Outside Command Context
137-
138-
If you need to use translations outside of a command context (such as in legacy commands), you can import the `locale` function directly:
139-
140-
```ts
141-
import { locale } from '@commandkit/i18n';
142-
143-
export async function run({ interaction, client }) {
144-
// This function can infer the locale automatically
145-
const { t } = locale();
146-
147-
return interaction.reply({
148-
content: t('response', { latency: client.ws.ping }),
149-
ephemeral: true,
150-
});
151-
}
152-
```
153-
154-
This function works the same way as the one in the command context and can also infer the locale automatically based on the interaction.
13+
Check out [Localization with i18n](../../11-localization/01-i18n.mdx) for more details on how to use the i18n plugin.

‎apps/website/docs/guide/11-localization/01-introduction.mdx‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
title: i18n Plugin
3+
description: The i18n plugin for CommandKit enables internationalization (i18n) for CommandKit using i18next. It allows you to translate your application into different languages.
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
# i18n Plugin
10+
11+
The i18n plugin integrates [i18next](https://www.i18next.com/) into CommandKit, enabling you to create multilingual Discord bots that can automatically adapt to your users' preferred languages. This plugin provides seamless internationalization support for commands, events, and all bot interactions.
12+
13+
## Features
14+
15+
- 🌍 **Automatic locale detection** - Automatically uses Discord's guild preferred locale
16+
- 🔧 **Easy setup** - Simple configuration with sensible defaults
17+
- 📁 **File-based translations** - Organize translations in JSON files
18+
- 🎯 **Context-aware** - Access translations in commands, events, and legacy handlers
19+
- 🔌 **i18next ecosystem** - Full compatibility with i18next plugins and features
20+
- 📝 **Command metadata localization** - Localize command names, descriptions, and options
21+
22+
## Installation
23+
24+
<Tabs>
25+
<TabItem value="npm" label="npm">
26+
27+
```bash
28+
npm install @commandkit/i18n
29+
```
30+
31+
</TabItem>
32+
<TabItem value="yarn" label="yarn">
33+
34+
```bash
35+
yarn add @commandkit/i18n
36+
```
37+
38+
</TabItem>
39+
<TabItem value="pnpm" label="pnpm">
40+
41+
```bash
42+
pnpm add @commandkit/i18n
43+
```
44+
45+
</TabItem>
46+
</Tabs>
47+
48+
## Basic Setup
49+
50+
Add the i18n plugin to your CommandKit configuration:
51+
52+
```ts
53+
import { defineConfig } from 'commandkit';
54+
import { i18n } from '@commandkit/i18n';
55+
56+
export default defineConfig({
57+
plugins: [i18n()],
58+
});
59+
```
60+
61+
## Advanced Configuration
62+
63+
You can customize the i18n plugin by passing options to it:
64+
65+
```ts
66+
import { defineConfig } from 'commandkit';
67+
import { i18n } from '@commandkit/i18n';
68+
// Import any i18next plugins you want to use
69+
import Backend from 'i18next-fs-backend';
70+
import { initReactI18next } from 'react-i18next';
71+
72+
export default defineConfig({
73+
plugins: [
74+
i18n({
75+
plugins: [someI18nextPlugin],
76+
// Add other i18next configuration options as needed
77+
}),
78+
],
79+
});
80+
```
81+
82+
## Translation Files Structure
83+
84+
Create a `locales` directory inside your `src/app` folder with subdirectories for each language. Each language directory should contain JSON files for your translations.
85+
86+
```
87+
src
88+
└── app
89+
├── locales
90+
│ ├── en-US
91+
│ │ └── ping.json
92+
│ │ └── messageCreate.event.json
93+
│ └── fr
94+
│ └── ping.json
95+
│ └── messageCreate.event.json
96+
├── commands
97+
│ ├── ping.ts
98+
│ └── help.ts
99+
└── events
100+
└── messageCreate
101+
└── handler.ts
102+
```
103+
104+
### Supported Locales
105+
106+
CommandKit uses Discord's locale identifiers. Please refer to [Discord's Locales documentation](https://discord.com/developers/docs/reference#locales) for a complete list.
107+
108+
## Quick Start Example
109+
110+
Here's a complete example to get you started:
111+
112+
1. **Configure the plugin**:
113+
114+
```ts title="commandkit.config.ts"
115+
import { defineConfig } from 'commandkit';
116+
import { i18n } from '@commandkit/i18n';
117+
118+
export default defineConfig({
119+
plugins: [i18n()],
120+
});
121+
```
122+
123+
2. **Create translation files**:
124+
125+
```json title="src/app/locales/en-US/ping.json"
126+
{
127+
"$command": {
128+
"name": "ping",
129+
"description": "Check the bot's latency"
130+
},
131+
"response": "🏓 Pong! Latency: **{{latency}}ms**"
132+
}
133+
```
134+
135+
```json title="src/app/locales/fr/ping.json"
136+
{
137+
"$command": {
138+
"name": "ping",
139+
"description": "Vérifier la latence du bot"
140+
},
141+
"response": "🏓 Pong! Latence: **{{latency}}ms**"
142+
}
143+
```
144+
145+
3. **Use translations in your command**:
146+
147+
```ts title="src/app/commands/ping.ts"
148+
import type { ChatInputCommand, CommandData } from 'commandkit';
149+
150+
export const command: CommandData = {
151+
name: 'ping',
152+
description: "Check the bot's latency",
153+
};
154+
155+
export const chatInput: ChatInputCommand = async (ctx) => {
156+
const { t } = ctx.locale();
157+
158+
await ctx.interaction.reply({
159+
content: t('response', { latency: ctx.client.ws.ping }),
160+
});
161+
};
162+
```
163+
164+
That's it! Your bot will now automatically respond in the user's guild preferred language.

0 commit comments

Comments
 (0)