LanguageRepository.java

LanguageRepository is the core localization component for all NyaaCat plugins. It's extensively used so you can check any of our plugin for usages.

Usage Paradigm

public class I18n extends LanguageRepository { // You need to extend the LanguageRepository
    public static I18n instance = null;
    private String lang = null;
    private final NyaaUtils plugin;

    @Override
    protected JavaPlugin getPlugin() { // will be called by super.load()
        return plugin;
    }

    @Override
    protected String getLanguage() { // will be called by super.load()
        return lang;                 // used to determine the preferred language
    }

    public I18n(NyaaUtils plugin, String lang) {
        instance = this;
        this.plugin = plugin;
        this.lang = lang;
        load(); // call load() to load the language items
    }

    public static String format(@LangKey String key, Object... args) { // Make getFormatted() static so can be used with ease
        return instance.getFormatted(key, args);
    }
}

Language Items

A language item is the minimal single element can be translated. I can be a word, a sentence or a paragraph. Language items are stored in YAML files. For example:

root:
  item1: This is a sentence
  item2: This is another sentence

This YAML file consists of two language items:

• root.item1: This is a sentence
• root.item2: This is another sentence

Language items are also referred to as language key-value pairs. In the example above, root.item1 and root.item2 are the language keys. This is a sentence and This is another sentence are their values.

Internal Section & Normal Section

Language items have their keys start with internal. are internal language items. These language items are usually used for internal error message or common prompt shown by other components of NyaaCore (e.g. CommandReceiver). The internal items are mainly provided bundled together with NyaaCore and get shared across all plugins using NyaaCore.

For language items other than internal items, they are normal language items. And is usually provided together with plugins depends on NyaaCore. They provide plugin-specific messages. Specially, plugins can also provide internal section items, which will overwrite the message only for that plugin.

Language Item Lookup

A language item is selected based on this priority:

1. Prefer language items of selected language rather than fallback language (i.e. en_US)
2. Prefer language items provided by specific plugin rather than those provided by NyaaCore.
3. Prefer language items in local files rather than in bundled files in jar.

For example, when preferred language is set to zh_CN, an English message may be shown if Chinese language item is found in none of these places:

• plugin's config folder
• plugin jar file
• NyaaCore config folder
• NyaaCore jar file

If the language item cannot be found even for the fallback language, some internal structures may be printed and a warning will be printed in the console.

File Locations

• Bundled: <plugin_name>.jar/lang/<lang_code>.yml
• Local: plugins/<plugin_name>/lang/<lang_code>.yml

Note that a local language file will be automatically created and used since then. If you want to ignore all local language files, you can pass argument

-Dnyaautils.i18n.refreshLangFiles=true

ILocalizer.java

The sole purpose of this interface is to decouple CommandReceiver with LanguageRepository So plugin developers can use CommandReceiver with their own L10n system.