LocaleAPI - Locale API for Sponge plugins

Semenkovsky_Ivan February 14, 2022, 3:05pm 1

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

LocaleAPI

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
language.

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.
./{ConfigDir}/localeapi/{pluginid}/[LocaleFiles]
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(API8-10). 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
choose.
For the correct work of the plugin is necessary to generate a default localization file - en-US.

github.com/SawFowl/LocaleAPI

README.md

API12

# LocaleAPI [![jitpack](https://jitpack.io/v/SawFowl/LocaleAPI.svg)](https://jitpack.io/#SawFowl/LocaleAPI)

API for working with plugin localizations on SpongeAPI7+. \
Test plugin -> <https://github.com/SawFowl/LocaleTestPlugin/tree/API11> \
javadoc -> <https://sawfowl.github.io/LocaleAPI>

```JAVA
@Plugin("pluginid")
public class Main {
    private Main instance;
    private Logger logger;
    private static LocaleService localeService;
    private PluginContainer pluginContainer;
    public LocaleService getLocaleService() {
        return localeService;
    }

    @Inject
    public Main(PluginContainer pluginContainer, @ConfigDir(sharedRoot = false) Path configDirectory) {
        this.pluginContainer = pluginContainer;

This file has been truncated. show original

Semenkovsky_Ivan February 14, 2022, 3:07pm 2

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.

Semenkovsky_Ivan February 14, 2022, 3:10pm 3

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.

airdest July 21, 2022, 11:12am 4

Great work！it is very elegant and useful.

1 Like

Semenkovsky_Ivan August 20, 2022, 8:32am 5

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

Adding functionality to the SerializedItemStack class.
Addition of localization creation/reloading events.
Adding text replacement functionality.
Fixed localizations tracking in json files.

Semenkovsky_Ivan November 5, 2022, 4:17pm 6

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

Added TextUtils class

Semenkovsky_Ivan January 18, 2023, 3:37pm 7

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

During the previous plugin update, the wrong file was loaded on ORE by mistake.

Semenkovsky_Ivan February 25, 2023, 9:01pm 8

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

Various fixes and improvements to the API.

Semenkovsky_Ivan March 2, 2023, 6:04pm 9

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

Fixed stopping the tracking of changes in localization files when the server is shut down. Now the stop is correct.

Semenkovsky_Ivan May 6, 2023, 10:33pm 10

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

Added DataContainer serializer.

Semenkovsky_Ivan October 26, 2023, 8:39pm 11

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

1.19.4+ !!!

Java 17 is used.
Update to SpongeAPI10.
Improved plugin and text processing API.
Changed text record in json format. Now it has expanded view instead of single line view.
Added serializers for ItemStack and JsonObject classes.

Semenkovsky_Ivan December 17, 2023, 7:26pm 12

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

Added the ability to use `ValueReference`.

Now it is possible to assign serializable classes to localizations.
This functionality should simplify the use of localizations, as well as slightly improve performance when getting objects of type Component, because it will not be necessary to deserialize it from the configuration every time.
The new functionality applies only to file formats supported by Sponge.

Semenkovsky_Ivan January 27, 2024, 11:01am 13

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

Implemented 2 new ways to change NBT tags of items.
Added implementation of placeholders.
Improved JsonObject serialization.
Minor fixes.

Semenkovsky_Ivan June 19, 2024, 7:48pm 14

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

Upgrade to SpongeAPI 11.

The API for writing tags to items has been replaced by an API for writing components. Backward compatibility is not - guaranteed.
Added annotation to localize comments in the configuration.
Added annotation to localize comments in the main plugin configuration.
The placeholder API has been improved.
Added default placeholders.

Semenkovsky_Ivan July 23, 2024, 1:33pm 15

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

API12

Added logger creation with conversion of Minecraft/RGB/Hex colors to ANSI format.
If the serializable class has been changed, when it is saved again, the new elements will be scanned and added to the config.
The automatic reloading of localizations has been redesigned.

Due to ORE restrictions on the number of colors for tags possible when publishing a new version of the plugin, all new versions will be published with one of two tags - Release or UNSTABLE.

Semenkovsky_Ivan February 9, 2025, 11:38pm 16

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

The performance of tracking changes to files has been significantly improved. The file tracking code has been completely replaced.
The plugin no longer causes the server to hang on shutdown.

Semenkovsky_Ivan February 10, 2025, 10:14am 17

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

Localization file events have been returned.

Outfit8TSB February 11, 2025, 11:06am 18

aw ivan, i was about to develop the same thing.

Semenkovsky_Ivan March 20, 2026, 4:58pm 19

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

Redesigned the API. It should be more convenient now.
An API has been added to simplify working with plugin configurations. It will be redesigned in the future for more convenience.
Support for '.properties` files has been removed. It may be returned in the future, but that’s not for sure.

Semenkovsky_Ivan April 10, 2026, 12:24pm 20

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

The plugin’s API has been improved for greater convenience when working with it.
Previously, the plugin could only work with Hocon, Json, and Yml. The plugin can now work with the following list of configuration file loaders:

Hocon - Standard Sponge configuration. Has some similarities with Json. Supports comments.
Json - Alternative configuration format. Classic Json. Does not support comments.
Yaml - An alternative Sponge configuration format that uses a block structure and is easy to read. Currently, it does not support comments, but this may be fixed in the future by the Sponge team.
GeyserYaml - An alternative Sponge configuration format that uses a block structure and is easy to read. It supports comments. Support for this loader is experimental.
Jackson - An alternative Sponge configuration format in json format that does not support comments.
XML - An alternative Sponge configuration view that supports comments but is not easy to read.
Toml - Using the LocaleAPI-generated Toml format configuration loader. Easy to read. Supports comments. It is not recommended for localizations, as errors may occur during subsequent conversion from it to any other format due to the incompatibility of Toml with the json data format.

The server administrator will now be able to override the configuration type used for other plugins that depend on the LocaleAPI. The change can be global or applicable to a specific plugin.
Now the server administrator will be able to change the directory for saving localization files.