Localization System

TomoriBot localizes user-facing text through locale files in src/locales/.

Supported Locales

Currently loaded from source:

• en-US (default fallback)
• ja

Runtime Architecture

• Loader: src/utils/text/localizer.ts
• Locale structure: src/locales/{locale}/ directories, one .ts file per category
• Categories: general, commands, providers, tools, bridges
• At boot, initializeLocalizer() scans each locale directory, imports all category slices, and merges them into a single tree via Object.assign
• Locale values are nested objects, accessed through dot-path keys

Example lookup:

localizer(locale, "commands.config.setup.description")

Important Behaviors

• initializeLocalizer() must run during startup before lookups.
• Missing locale code falls back to en-US.
• Missing key falls back to returning the key string.
• Multi-line strings are dedented automatically on load.

Locale File Shape

Each locale exports a nested object (not a flat key-value map).

export default {
  commands: {
    config: {
      setup: {
        description: "...",
      },
    },
  },
};

Slash Command Metadata Localization

commandLoader.ts auto-generates description/choice localizations from locale keys.

Recommended pattern in command files:

• set base metadata with localizer("en-US", key)
• do not hardcode localized setDescriptionLocalizations(...) per command

Key conventions:

• Subcommand description:
  • commands.{category}.{path}.description
• Option description:
  • commands.{category}.{path}.{option_name}_description
• Choice label:
  • commands.{category}.{path}.{option_name}_choice_{choice_value}

User Language Preference

• User preference is stored in users.language_pref.
• Most interaction replies receive locale/userData.language_pref and should use that for response text.

Adding or Changing Locale Keys

1. Update the appropriate category file under src/locales/en-US/ (e.g. commands.ts, general.ts).
2. Mirror the same key structure in the corresponding src/locales/ja/ file.
3. Run:

bun run check-locales

This validates cross-locale key parity and catches missing keys.

Best Practices

• Localize all user-facing command/embed strings.
• Keep command metadata keys aligned with command path conventions.
• Avoid hardcoded strings in command implementations.