Using the LanguageAPI

Basics

LanguageAPI is an API for internationalizing plugins.

Theory

The LanguageAPI is an API that can be queried to retrieve a localized message for a specific user. Before this, the localized message has to be loaded inside the API and the user has to set the language.

Each string in the LAPI has its own id - by this id you can get and load these strings.

The class LAPI is a starting point for using LAPI.

Load locales

LAPI.loadLocale(
    "ru.ancap.framework.messages.example", // message id
    "Russian localized message example", // message localization
    Language.RU // localization language
);

Set language for player

LAPI.setupLanguage(
    Player#getName, // player id for saving his language
    Language.RU // setting language of the player
);

Get localized message

return LAPI.localized(
    "ru.ancap.framework.messages.example", // message id
    Player#getName() // id of the player, for which to return the localized message
);

Production use

However, it is not always convenient to use the above low-level operations. AncapFramework provides alternative, more convenient ways to load locales into the LAPI.

Writing locales as a .yml file

AncapFramework provides the following standard for writing locales as a .yml file:

language: ru

ru:
  ancap:
    framework:
      messages:
        languages:
          en: "Russian"
          en: "English"
        no-args: "Not enough arguments. You need more %COUNT% than entered."
        unknown-command: "Unknown command: %COMMAND%".
        no-perms: "You must have %PERMISSION% permission to do this!"
        enter-language: "The /language command is intended for selecting the server language. Use it as follows: /language set <language code> where the language code can be anything from the ISO 639-1 standard.
        incorrect-args: "Invalid argument \"%ARG%\"."
        language:
        change: "Your language has been changed to %LANG%."

In the root of the file there should be a record language: <lang> telling which locales are described in the file.

Automatic loading of locales

To automatically load locales into the LAPI, name the locales files as locale_<number>.yml, where are consecutive locale numbers (starting with zero) and place these files in your plugin's resource folder. When you call the this.loadLocales() method from the AncapPlugin descendant, these files will automatically load into the database.

LAPIMessage

LAPI can be integrated with CommunicatorAPI and send LAPIMessage to players:

Communicator communicator = new Communicator(sender);
Communicator.send(new LAPIMessage(
    Artifex.class, "not-enough-money",
    new Placeholder("lack", new Message(item.price() - player().balance()))
));

Features of LanguageAPI implementation in Artifex

The LanguageAPI implementation in Artifex allows players to choose their own server language with the command /language set <code>.