Localisation

Localisation simply refers to the process of translating text within an application to that of a user's preferred language. In IB.ai we achieve that with the i18n package, located at /src/main/java/com/ibdiscord/i18n. The lang directory is located at /lang/.

Process for adding a new language.

1. Duplicate the 'en' (English) directory, from /lang/
2. Rename it to the new language
3. Add the language to the available_languages.json file
4. Start translating line-by-line. Leave all English translations in place until a suitable foreign translation has been made

Usage in-code

Basics

To reference the main 'localiser' method (public String translate(CommandContext context, String key, Object... format)), you should use LocaliserHandler.INSTANCE.translate(CommandContext context, String key, Object... format).

This is often not needed as the CommandContext has many helper methods that make using translations easy.

// Without i18n.
context.replyRaw("Consider it done");

// With i18n.
context.reply("success.done");

What this is doing internally is:

1. Finding the user's preferred language from the database (reason the context object is needed)
2. Looks in the JSON file 'feedback' (first half of the 'key' parameter)
3. Finds the string at the key 'done'. In this case, the string would be "Consider it done"
4. That value is returned as a string.

The JSON file that is queried can be found in the directory corresponding to the language of choice for the user. The names of the JSON files and the keys located within them are replicated across all of the different language directories. In the case of having Spanish and English options with the example above, the structure would look like:

lang/
  en/
    feedback.json
  es/
    feedback.json

Inside each feedback.json:

{
    "done": "Consider it done.",
}

{
    "done": "Considérelo hecho.",
}

If the user has Spanish as their preference, 'Considérelo hecho' would be sent once a command is successful.

The idea is that all Strings that are user-facing (including those in embedded messages) should at least be localised to English and found within the json files.

Complexity

Some strings may have variables inside of them. These are slightly more complicated. For example, Thank you, Pants, you are not a bot. would look like this:

{
    "thankUser": "Thank you, {0}, you {1} a bot.",
}

This example is a little contrived, but would look like this:

context.reply("feedback.thankUser", 
        context.getMember().getUser().getName(), 
        commandContext.getMember().getUser().isBot() ? "are" : "are not"
);

or...

{
    "userID": "Your user ID is: {0}.",
}

context.reply("feedback.userID", context.getMember().getUser().getId());