i18n & Localization

Build a multilingual bot using Kythia's built-in internationalization system — locale files, variable interpolation, and AI-powered auto-translation.

Kythia uses a file-based i18n system managed by the TranslatorManager. Every string shown to users should go through the translation function t() so that your bot can serve communities in their native language.

The TranslatorManager loads locale files in this priority order during boot:

Priority (highest to lowest)
─────────────────────────────
1. Addon lang files       addons/*/lang/*.json
2. User lang files        {appRoot}/lang/*.json
3. Core lang files        kythia-core/src/lang/*.json (built-in)

Higher-priority files override lower-priority ones by key. This lets your addons override core strings without touching the core package.

Place locale files at addons/{your-addon}/lang/{locale}.json:

// addons/leveling/lang/en.json
{
  "leveling": {
    "profile": {
      "title": "Profile — {{username}}",
      "level": "Level {{level}}",
      "xp": "{{current}} / {{required}} XP"
    },
    "set": {
      "success": "Set {{username}}'s level to {{level}}."
    }
  }
}

The translation function is injected into every command via the DI container:

async execute(interaction, container) {
  const { t } = container;

  // Simple key lookup
  const title = await t(interaction, 'leveling.profile.title', {
    username: interaction.user.username,
  });

  await interaction.reply(title);
}

The interaction parameter provides the user's locale (set in Discord's user settings). Kythia automatically falls back to en.json if the user's language isn't available.

Pass a second object argument with your variables. Use {{variableName}} in your JSON strings:

await t(interaction, 'leveling.set.success', {
  username: 'Alice',
  level: 25,
});
// → "Set Alice's level to 25."

npx kythia lang:translate --target id   # Indonesian
npx kythia lang:translate --target ja   # Japanese
npx kythia lang:translate --target zh   # Chinese

npx kythia lang:sync

npx kythia lang:check

Uses Babel AST parsing to scan all .js/.ts files for t('key') calls and compares them against your locale JSON. Reports:

• ❌ Missing keys — your code calls a key that doesn't exist in en.json
• ⚠️ Unused keys — a key exists in en.json but is never called in code

Kythia maps Discord's user locale codes to your locale files. Common codes: