BKCommonLib/Localization

« Go back

Introduction

BKCommonLib will create a Localization.yml file in the plugin's folder if the plugin contains localized keys or commands. Commands are automatically read from plugin.yml file in the plugin itself, which allows users to externally modify the usages and descriptions of commands without opening up the plugin in an archive extracting program.

The keys

Localization keys have to be lower-cased, otherwise they are not detected and probably overwritten as well. This is important later on, if you want to make argument-specific nodes. They have to be lower-case too.

Colors

The § 'text formatting code' can be used to add colors and other formatting styles to the messages. See this page for more information about the characters to put after this sign.

Arguments

Some localization nodes allow arguments from the plugin to be passed into the message. These arguments are surrounded by percentage signs. %0% is the first argument, %1% is the second argument, and so on. This identifier does not have to be in the message, you can leave it out.

Argument specific nodes

It is possible to use completely different messages for different arguments from the plugin. For example, there is the player.enter node that looks like this:

someplugin:
  player:
    enter: §ePlayer %0% joined the server! Say hello!

You can give a special welcome message to the player called player1:

someplugin:
  player:
    enter:
        default: §ePlayer %0% joined the server! Say hello!
        player1: §eThe magnificent player1 joined the server, bow before his might!

This applies to all nodes that have an input argument. It is possible to extend this logic for two arguments as well, for example:

someplugin:
  use:
    default: You used a %0% against a %1%!
    sword:
      default: You used a powerful sword against a %1%

     block: You used a sword against a block, it's not very effective!

Note how the second argument is still %1%. The argument key stays the same for sub-argument nodes. This is to prevent confusion when copy-pasting the same message and allow small modifications. Otherwise you would have to change all %0% arguments to the argument name, which can be tiresome.

Example in MyWorlds

You can set an enter message for worlds. This example has a special enter message for world1 and Lowgrass:

world:
  enter:
    default: §aYou teleported to world '%0%'!
    world1: §aYou teleported to world 1, have a nice stay!
    lowgrass: §aYou teleported to the nicely built Lowgrass, have fun there!

As can be seen, the node is a lowercase lowgrass and not Lowgrass. As stated in the beginning, localization keys have to be lower case.

Internals

You can skip this part if you are not programming using the library. BKCommonLib features built-in Localization reading for plugins extending the PluginBase in BKCommonLib. It automatically manages localization nodes reading and writing from/to the Localization.yml file in the plugin's folder.

This localization system automatically reads all command descriptions and usages found in the plugin.yml of your plugin and makes them configurable in the Localization.yml file. Alternatively, the plugin can add more nodes using the loadLocale(path, value) method. This method will check the localization file for the node, and if it doesn't exist, it adds the default value specified to it. This should be done in the localization() method, which is fired right before enabling the plugin.