Skip to content

Localizer

Jump to bottom
Florian Fülling edited this page Jun 3, 2021 · 1 revision

The Localizer is a nearly plug and play Localizer .

Setup

  1. Create a resource bundle in your project.
  2. Create a default properties without a locale code.
  3. Create at least one file with a locale code. This will be our fallback file.

Now your bundle maybe looks like this:
properties

Now we are ready to initialize our Localizer instance we will use.

Localizer localizer = new Localizer(this, config.getLanguage(), "messages", "messages", Locale.US, "de_DE", "en_US");

The signature of the Localizer constructor is:

Localizer(Plugin plugin, String language, String localesPath, String localesPrefix, Locale fallbackLocale, String... includedLocales)
  • plugin: This should be your own plugin instance. We need this for logging.
  • language: is the language the user requests via the config or however. It doesn't matter if this key exists. (More later)
  • localesPrefix: the prefix of the properties files. In our example its "message". This is also the name of your resource bundle.
  • fallbackLanguage: the fallback language the plugin will use if a key is missing or empty. This locale should be complete. I recommend to use the english version.
  • includedLocales: Enter all the locales you have in your resource bundle. In our case we have German and English.

Sitenote: We use the standard locale codes these can be en_US or just en or de or whatever. They don't have to exist as long as the format is ok.

Now with this we are good to go.

Usage

The usage is fairly simple.
To get a key just call the getMessage() method of the Localizer instance.

String message = localizer.getMessage("my.key");

You will receive the message in the requested language or in the language of the fallback file if the value of this key is empty or it does not exist (Sidenote: It is nearly impossible that a key does not exist. Later more.)

Replacements

In the most cases a normal feedback message is not always the same. We want to add some more data which is based on the current case.
So we need a way to replace.

When you get a message you can also provide replacement objects.
A replacement object is created with one of the create methods of the replacement object.

Replacement.create("PLACEHOLDER", "replacement");

This will replace a marker in the message. In this case it is %PLACEHOLDER% which will be replaced with replacement the % surrounding the placeholder are added by the Localizer.

In the most cases we also want to highlight our replacement.
You can directly make a chained call on the replacement object to do this.

Replacement.create("PLACEHOLDER", "replacement").addFormatting('6', 'l');

Now the replacement will have a golden color and bold formatting (Note: The formatting code here is §r§6§l. The formatting is always reset before applied). After a replacement a §r is appended to reset the formatting. You can add formatting for this too.

Replacement.create("PLACEHOLDER", "replacement").addFormatting(new char[] {'6', 'l'}, '2');

The complete replacement would look like this: §r§6§lreplacement§r§2.

You can also say that a placeholder should not be case sensitive.

Replacement.create("PLACEHOLDER", "replacement").ignoreKeyCase();

Of course you can chain a formatting there as well.

So in the end it would look like this:

String message = localizer.getMessage("my.key",
    Replacement.create("PLACEHOLDER", "replacement").addFormatting(new char[] {'6', 'l'}, '2'),
    ...);

Change locale

If you want to change the locale after creation you can call the setLocale() method. This can be useful if you want to change the language after a reload.

localizer.setLocale("de_DE");

Background Process

The Localizer does not only read a property file. It does a lot more.

Creating

On start the Localizer will copy all files to the localesPath from the resources, if the do not exist there.

Updating

After creating default files a update process it triggered. The Localizer will load all existing locale files in the locales path. Locales which are not part of the plugin as well.

The Localizer will check if all keys from the reference file (The file without a locale code) are present in the file. If not it will add them. This key will also get a value if a locale file is present in the resources folder. So you don't have to care about updating your files.

When a file was updated a timestamp will be entered as a header when the file was updated. The user will also be notified that its locale file was updated.

Clone this wiki locally