Internationalization (i18n)

Locales

Locales represent specific geographical, political, or cultural regions. In the context of programming, Locale objects are used to represent a set of language, script, region, variant, and extensions, which can be used together to format all kinds of data or to look up translations.

Discord has a predefined set of supported locales, which may be found here. This list of locales represents those supported by the Discord client and isn't an exhaustive list of all possible locales.

Kord Extensions uses locale resolvers to find the relevant Locale object for any given event. You can configure them in your bot's i18n builder.

You may want to consider writing a custom resolver and allowing users to configure their preferred locale using commands if you want to support locales other than those in the Discord client.

Translation Bundles

The most important unit in the i18n system is the translation bundle. By default, Kord Extensions uses properties-based Java Resource Bundles, where translations are stored in a set of .properties files with similarly prefixed names. Translation bundles are represented using Bundle objects in code.

The first thing you'll need to do is pick a name for your translation bundle. The name should contain two parts — the name of the containing folder, and the bundle itself — split using a dot or period (.). This name is used to locate the resource bundle in your bot's resources, within the translations/ base directory.

For example, mybot.strings refers to a resource bundle named strings stored within translations/mybot/ in your bot's resource files.

Your translation bundle must contain a base translation file, with a set of default translations. This file should be named without a locale, so in the above example, it'd be named strings.properties. The translations in this file will be used as a fallback when a translation is missing.

All other translations must be placed in translation files containing the relevant locale code. For example, the locale code for German is de, so a translation file for German in our example would be named strings_de.properties.

For more information on the properties file format, see this page on Wikipedia.

Translation Keys

A translation key represents a single translation. When you store translations in a properties file, they're referred to by name. For example:

In the above properties file, command.about.name is a translation key, referring to a specific translation.

Translation keys are represented using Key objects in code. These objects may also contain bundle and locale information with predefined replacement values, as explained in below.

Empty Translations

For translation keys that support an empty value for specific locales, you may provide a special value for the translation. This value consists of three empty set characters (∅∅∅) and should contain nothing else.

Note: This value is not supported for all translations. You can use it in the following places:

• Chat command aliases

• Ignored words in duration parsers

• Initial values for text input widgets

• Reset words for the PluralKit module

Placeholder Substitution

ICU Message Format allowed for two types of placeholders:

• Ordinal placeholders: Hello, {0}!

  Ordinal placeholders are filled using an array of arbitrary values. Array indices are specified by placing them within curly braces.

  For example, to specify the first element of the array, you would use {0}.

• Named placeholders: Hello, {name}!

  Named placeholders are filled using a string-keyed map of arbitrary values. The map's keys are specified by placing them within curly braces.

  For example, to specify the name key of the map, you would use {name}.

Mixed placeholder types are unsupported, so you'll need to pick one or the other. We recommend using named placeholders, as they result in more readable translations.

Placeholders are automatically formatted using the default ICU formatter for the corresponding type. However, you can further format placeholders by supplying a style modifier.

Numeric Formatting

ICU Message Format provides several useful modifiers you can use to format numeric types. The following examples use 0 in place of any ordinal or named placeholder you may use.

Selections

Selections are a more advanced formatting construct that allows you to provide different translations based on a set of rules. The following examples use 0 in place of any ordinal or named placeholder you may use.

Creating Keys

If you're using the KordEx Gradle plugin, you can configure it to generate translation classes from your translation bundle.

This is the recommended approach and will result in a tree of translation classes containing generated Key objects that you can reference in your code. If you can't use the Gradle plugin, you can find a CLI tool and an API in this GitHub repository, to integrate with your own tooling.

Alternatively, Key objects can be manually constructed as required, or created from String keys using the String.toKey(bundle?, locale?, presetPlaceholderPosition?, translateNestedKeys?) extension function.

Configuring Keys

Key objects are immutable, but they provide several functions that allow you to configure cloned objects.

To create a copy of the Key with a bundle or locale, you can use the withBundle, withLocale or withBoth functions, or with the withContext function to copy the locale from a command context. Creating a copy without either a bundle or locale can be done by calling the corresponding without functions.

To create a copy with more pre-defined placeholders, use the withOrdinalPlaceholders or withNamedPlaceholders functions. You can create a copy without pre-defined placeholders by calling the corresponding without functions, or create a copy with a set of filtered placeholders using the corresponding filter functions.

To create a copy with an additional post-processor (which you can use to manipulate the result of a translation), use the wthPostProcessor DSL function. To add multiple, you can use withPostProcessors. It's also possible to remove post-processors using the filterPostProcessors function.

To create a copy with updated settings, use the withPresetPlaceholderPosition or withTranslateNestedKeys functions.

Key Utilities

Kord Extensions provides a number of additional utility functions.

• capitalize - Creates a clone of the current Key, with an additional post-processor which capitalizes the first character of the translated string. It uses the Key's locale, or your bot's configured default locale if one isn't present.

• capitalizeWords - Creates a clone of the current Key, with an additional post-processor which capitalizes each word in the translated string. It uses the Key's locale, or your bot's configured default locale if one isn't present.

• lowercase - Creates a clone of the current Key, with an additional post-processor which lower-cases each character in the translated string. It uses the Key's locale, or your bot's configured default locale if one isn't present.

• uppercase - Creates a clone of the current Key, with an additional post-processor which upper-cases each character in the translated string. It uses the Key's locale, or your bot's configured default locale if one isn't present.

• withContext - Creates a clone of the current Key, updating its stored locale to match the one corresponding with the given CommandContext.

Translating Keys

When you find a property or function expecting a Key object, it's enough to configure the key as explained above and use it directly. For situations where you need to translate a Key yourself, you'll need to use one of the provided translation functions.

The translate and translateArray functions can be used to translate the current Key with a set of ordinal placeholders. If any pre-defined ordinal placeholders are present, they'll be used based on the presetPlaceholderPosition setting.

The translateNamed function can be used to translate the current Key with a set of named placeholders. If any pre-defined named placeholders are present, they'll be used based on the presetPlaceholderPosition setting.

All translation functions include a version suffixed with Locale, which will use the given locale for translation if the Key doesn't already have a locale set.

Putting It All Together

To better illustrate how you might use translation keys, consider this example: