Skip to main content

Localization

The Localizer reads your texts from .properties files, one per language. The hub uses it for command names and descriptions, and you use it for every reply.

Create the localizer​

Localizer localizer = Localizer.builder(DiscordLocale.ENGLISH_US)
.addLanguage(DiscordLocale.GERMAN, DiscordLocale.FRENCH)
.withLanguageProvider(guild -> settings.language(guild))
.withGuildLocaleCodeProvider((guild, key) -> Optional.empty())
.build();
MethodDefaultWhat it does
addLanguage(DiscordLocale...)only the default languageThe languages your bot ships.
withBundlePath(String)localeBase name of the resource bundles.
withLanguageProvider(...)the guild's Discord localeReturns an Optional<DiscordLocale> with the language a guild chose, for example from your database. Empty means the guild's Discord locale.
withGuildLocaleCodeProvider(...)no overridesLets a guild override single keys. Return Optional.empty() to use the files.

Pass the localizer to the hub with withLocalizer(localizer). Pages, menus, modals and conversations use it then too.

Locale files​

The files live in your resources and follow the ResourceBundle naming: the bundle path, an underscore and the language with an underscore instead of a dash.

src/main/resources/
├── locale.properties
├── locale_en_US.properties
├── locale_de.properties
└── locale_fr.properties

locale.properties is the base bundle. Keys missing in a language are taken from it, so it is a good place for every key. When the localizer starts, it warns about keys that are missing in one of the languages.

command.invite.message.title=Invite me
command.invite.message.click=[Click here](%URL%)
command.dashboard.message.topUser=Highest $words.reputation$
words.reputation=Reputation

Keys and replacements​

There are two ways to write a text:

  • A plain key such as command.invite.message.title is looked up as a whole. A key has at least one dot and uses letters, dots and underscores.
  • Any other text is kept as it is, and every $key$ inside it is looked up. This lets you mix keys and text: "$command.vote.field.streak$: 5".

Values are looked up again after the replacements, so a value can contain $other.key$.

Replacements fill %NAME% placeholders:

context.localize("command.invite.message.click", Replacement.create("URL", inviteLink));
FactoryPlaceholderValue
Replacement.create("KEY", value)%KEY%String.valueOf(value)
Replacement.create("KEY", value, Format.BOLD)%KEY%the value in bold
Replacement.createMention(member)%USER%the mention
Replacement.createMention(role)%ROLE%the mention
Replacement.createMention(channel)%CHANNEL%the mention
Replacement.createMention("KEY", mentionable)%KEY%the mention

Placeholders match without regard to case. Call matchCase() on a replacement to only replace the exact case. Format also has ITALIC, UNDERLINE, CODE and CODE_BLOCK.

Which language is used​

You callLanguage
context.localize(...) in a handlerThe guild's language in a guild, the user's language in DMs.
context.guildLocalizer().localize(...)The guild's language.
localizer.localize(key, guild, ...)The guild's language.
context.userLocalizer().localize(...)The user's client language.
localizer.localize(key, locale, guild, ...)The given language.

The guild's language is the one your language provider returns, else the guild's Discord locale. Embeds, menu labels and modal labels use it too. A language you did not add falls back to the default language. A key missing everywhere comes back as the key itself, with a warning.

Embeds​

LocalizedEmbedBuilder is an EmbedBuilder that localizes everything you put in:

MessageEmbed embed = new LocalizedEmbedBuilder(context.guildLocalizer())
.setTitle("command.invite.message.title")
.setDescription("command.invite.message.click", Replacement.create("URL", inviteLink))
.build();

Quieter logs​

Command names often have no translation on purpose. Set cjda.localisation.error.name=false (system property) or CJDA_LOCALISATION_NAME_ERROR=false (environment) to stop warnings about missing .name keys.