LocaleAPI - Locale API for Sponge plugins

This is a discussion topic for the Ore project, LocaleAPI. View the full project on Ore for downloads and more information.


What is it for? Developers using this API can provide the ability to
simultaneously use multiple languages.
For example. On your server there are players from different countries
and they understand only their language. If there is a localization file
in which there will be messages corresponding to the client language
chosen by them, they will see the messages of your plugin in that

For server admin:

All localization files are saved in the following path, where “pluginid”
is the directory for the localization files of a particular plugin.
This only applies to plugins that use LocaleAPI.
You can add translation files you need to the plugin localization
directory. When you add a localization file, it will be downloaded automatically. If you make changes to existing files, they will also be automatically reloaded. The load/reload operation cannot be performed more than once every 10 seconds. This time limit has been added to eliminate the possibility of server performance degradation.

For developers:

The localization file name must be in the format en-US, ru-RU, etc.
Select the file type depending on which configuration you prefer to
For the correct work of the plugin is necessary to generate a default localization file - en-US.

Test plugin → GitHub - SawFowl/LocaleTestPlugin: Test LocaleAPI.
javadoc → Overview (LocaleAPI 2.1.0-S8.0.0-RELEASE API)

public class Main {
	private Main instance;
	private Logger logger;
	private static LocaleService localeService;
	public LocaleService getLocaleService() {
		return localeService;

	// Get API. Variant 1. This happens in event `ConstructPluginEvent`.
	// It's recommended if LocaleAPI is mandatory.
	public void onLocaleServisePostEvent(LocaleServiseEvent.Construct event) {
		instance = this;
		logger = LogManager.getLogger("PluginName");
		localeService = event.getLocaleService();

	// Get API. Variant 2. This happens in event `StartedEngineEvent<Server>`. 
	// It's recommended if LocaleAPI is optional.
	// In this case, you can specify another class as the event listener.
	public void onLocaleServisePostEvent(LocaleServiseEvent.Started event) {
		localeService = event.getLocaleService();

	public void testLocales() {
		if(!localeService.localesExist(instance)) {
			localeService.createPluginLocale(instance, ConfigTypes.HOCON, Locales.DEFAULT);
			//		                  ^^ Main class or "pluginid".
				.checkString("Your string for localization.", "Optional comment", "Path");
		// Get message from locale. You can get and use the player's localization 'player.locale();'.
		// The boolean parameter defines what type of string serializer will be used.
		logger.info(getLocaleUtil(Locales.DEFAULT).getComponent(false, "Path"));

	public AbstractLocaleUtil getLocaleUtil(Locale locale) {
		return localeService.getOrDefaultLocale(instance, locale);
repositories {
	maven { 
		name = "JitPack"
		url 'https://jitpack.io' 
dependencies {
	implementation 'com.github.SawFowl:LocaleAPI:2.1.0'

A new version has been released for LocaleAPI, it is available for download here.

Version for API7.
Further development of this version has been discontinued.

A new version has been released for LocaleAPI, it is available for download here.

Version for API8.
API has become easier.
Now there will be tracking changes in localization files.
Localization by default is now always en-US.
Added the ability to serialize ItemStack. For configuration files, you must specify options that can also be obtained from this plugin. Localization files already use these options.
Changed the way to get API for localizations. Now events are used. The old way is marked as deprecated.