feat: use i18next based localizations

Author: twlite

apps/test-bot/src/app/locales/en-US/avatar.json

@@ -0,0 +1,13 @@
+{
+  "$command": {
+    "name": "avatar",
+    "description": "This is an avatar command.",
+    "options": [
+      {
+        "name": "user",
+        "description": "The user to get the avatar for."
+      }
+    ]
+  },
+  "avatar": "{{user}}'s avatar"
+}

apps/test-bot/src/app/locales/en-US/avatar.ts

@@ -0,0 +1,13 @@
+{
+  "$command": {
+    "name": "avatar",
+    "description": "C'est une commande pour afficher l'avatar.",
+    "options": [
+      {
+        "name": "user",
+        "description": "L'utilisateur dont vous souhaitez voir l'avatar."
+      }
+    ]
+  },
+  "avatar": "Avatar de {{user}}"
+}

apps/test-bot/src/app/locales/fr/avatar.json

@@ -27,7 +27,7 @@ export function run({ interaction }: SlashCommandProps) {
   const targetPetId = interaction.options.getString('pet');
   const targetPetObj = pets.find((pet) => pet.id === targetPetId);
 
-  interaction.reply(`Your pet name is ${targetPetObj.name}.`);
+  interaction.reply(`Your pet name is ${targetPetObj!.name}.`);
 }
 
 export function autocomplete({ interaction }: AutocompleteProps) {

apps/test-bot/src/app/locales/fr/avatar.ts

@@ -10,6 +10,7 @@ import { join } from 'node:path';
 import { devEnvFileArgs, prodEnvFileArgs } from './env';
 import { rimraf } from 'rimraf';
 import { performTypeCheck } from './type-checker';
+import { copyLocaleFiles } from './common';
 
 export interface ApplicationBuildOptions {
   plugins?: CompilerPlugin[];
@@ -80,6 +81,7 @@ export async function buildApplication({
       ],
     });
 
+    await copyLocaleFiles('src', dest);
     await injectEntryFile(configPath || process.cwd(), !!isDev, config.distDir);
   } catch (error) {
     console.error('Build failed:', error);

apps/test-bot/src/commands/old/legacy-autocomplete.ts

@@ -103,3 +103,30 @@ async function ensureExists(loc: string) {
 export function erase(dir: string) {
   rimrafSync(dir);
 }
+
+export async function copyLocaleFiles(_from: string, _to: string) {
+  const resolvedFrom = join(process.cwd(), _from);
+  const resolvedTo = join(process.cwd(), _to);
+
+  const localePaths = ['app/locales'];
+  const srcLocalePaths = localePaths.map((path) => join(resolvedFrom, path));
+  const destLocalePaths = localePaths.map((path) => join(resolvedTo, path));
+
+  for (const localePath of srcLocalePaths) {
+    if (!fs.existsSync(localePath)) {
+      continue;
+    }
+
+    // copy localePath to destLocalePath
+    const destLocalePath = destLocalePaths[srcLocalePaths.indexOf(localePath)];
+
+    if (!fs.existsSync(destLocalePath)) {
+      fs.promises.mkdir(destLocalePath, { recursive: true });
+    }
+
+    await fs.promises.cp(localePath, destLocalePath, {
+      recursive: true,
+      force: true,
+    });
+  }
+}

packages/commandkit/src/cli/build.ts

@@ -152,6 +152,8 @@ export async function bootstrapDevelopmentServer(configPath?: string) {
   const isConfigUpdate = (path: string) => {
     const isConfig = configPaths.some((configPath) => path === configPath);
 
+    if (!isConfig) return false;
+
     console.log(
       colors.yellowBright(
         'It seems like commandkit config file was updated, please restart the server manually to apply changes.',

packages/commandkit/src/cli/common.ts

@@ -14,7 +14,8 @@
     "@types/express": "^5.0.1",
     "commandkit": "workspace:*",
     "discord.js": "^14.17.3",
-    "tsconfig": "workspace:*"
+    "tsconfig": "workspace:*",
+    "typescript": "^5.8.3"
   },
   "files": [
     "dist",

packages/commandkit/src/cli/development.ts

@@ -20,3 +20,89 @@ export default defineConfig({
   plugins: [i18n()]
 })
 ```
+
+You can pass options to the plugin:
+
+```ts
+import { defineConfig } from "commandkit"
+import { i18n } from "@commandkit/i18n"
+
+export default defineConfig({
+  plugins: [
+    i18n({
+      plugins: [i18nextPlugins]
+    })
+  ]
+})
+```
+
+Create `locales` directory inside `src/app` and add your translation files. The directory structure should look like this:
+
+```
+src
+└── app
+    ├── locales
+    │   ├── en-US
+    │   │   └── ping.json
+    │   └── fr
+    │       └── ping.json
+    └── commands
+        └── ping.ts
+```
+
+CommandKit automatically localizes your commands if you follow the naming convention and translation file structure.
+
+If your translation file contains `$command` key with localization object, it will be used to localize the command name and description.
+
+```json
+{
+  "$command": {
+    "name": "Ping",
+    "description": "Ping the server",
+    "options": [
+      {
+        "name": "database",
+        "description": "Ping the database"
+      }
+    ]
+  },
+  "response": "Pong! The latency is {{latency}}ms"
+}
+```
+
+The `$command` key defines localization for the command name and description (or options). These properties are later merged with the actual command to build the final command object with localizations that Discord understands. Anything else in the translation file is used to localize the command response.
+
+This plugin adds `locale()` function to your command context. You can use it to localize your command responses.
+
+```ts
+export const chatInput: SlashCommand = async (ctx) => {
+  // ctx.locale() auto infers the localization of the current guild
+  // you can also pass a discord.js locale enum to use custom locale
+  // ctx.locale("fr") // uses french locale
+  const { t, i18n } = ctx.locale()
+  //      ^ TFunction
+  //         ^ i18next instance
+
+  ctx.interaction.reply({
+    content: t("response", { latency: client.ping }),
+    ephemeral: true
+  })
+}
+```
+
+Additionally, you can use the `locale()` function outside of the context to get the localization api. This is mostly useful if you are using `i18n` with legacy commands plugin.
+
+```ts
+import { locale } from "@commandkit/i18n"
+
+export async function run({ interaction }) {
+  const { t } = locale()
+
+  return interaction.reply({
+    content: t("response", { latency: client.ping }),
+    ephemeral: true
+  })
+}
+```
+
+This function is identical to the one in the context and it can also infer the locale automatically.

packages/devtools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commandkit/i18n",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CommandKit plugin that adds command localizations backed by i18next",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,4 +36,4 @@
     "tsconfig": "workspace:*",
     "typescript": "^5.7.3"
   }
-}
+}