[API] I18N - Internationalize your plugins! 0.7.0-SNAPSHOT

Register now to download for free
Internationalization API for use with CraftBukkit / Spigot

Internationalization API for use with CraftBukkit / Spigot​


Please note that this resource is a re-upload of my existing resource on Spigot! You may find the original resource here.

The I18N project aims to be an easy-to-use API for plugin developers to internationalize their plugins. I18N takes away a lot of the repetitive and tedious work that must be done in order to have the right translations in place and exposes a simple but powerful API that blends into the official Bukkit / Spigot API nicely.

Currently, I18N is still under heavy development and API changes are still possible. Yet the following features are currently working and tested for Minecraft version 1.9.2.

Basically, I18N allows you to easily manage players with different languages on your server by translating all text you usually send to a client for each player into his very own language automatically. You can make use of I18N with the following gameplay elements:

- [x] Chat messages
- [x] Actionbars
- [x] Titles / Subtitles
- [x] Scoreboards (teams, objectives, scores)
- [x] NEW in 0.3.1-SNAPSHOT: Signs

I18N depends on ProtocolLib for its injection functionality.

How does it work?

Just like any other plugin: simply put the .JAR file inside the plugins folder of your server and it will load during startup. Other plugins might depend on it as I18N exposes a translation API to plugin developers as well.

For server owners

If you are a server owner and you have been told that one of your plugin requires I18N to be installed in order to work properly you can download the latest version from the Maven repository down below. Please note, that I18N requires the latest version of ProtocolLib to be installed on your server.


Some parts of I18N can be configured and will be explained below. Note, that I18N uses SimpleConfig (see https://github.com/BlackyPaw/SimpleConfig) for its configuration files instead of YAML. The SimpleConfig format is in some ways less restrictive than the YAML format so it might be easier for you to edit.

# The fallback locale to use for players whose locale could not be resolved (language code only)
fallbackLocale: "en"
# Whether or not failed translation attempts should be re-attempted using the fallback locale configured above
useFallbackLocale: true
# If set to true the localizer used by this plugin itself will be allowed to lazy load user translations inside the translations folder
allowUserTranslations: false
# If set to true the native names of languages will be displayed. If set to false their english names will be displayed instead
useNativeLanguageNames: true
# The locale resolver to be used per default unless another plugin changes it programmatically.
# May be one of the following constants:
# - CONSTANT : The fallback locale will be returned for all players
# - DATABASE : Player locales will be resolved from a MySQL database (slow)
defaultLocaleResolver: "DATABASE"
# For use with DATABASE locale resolver: Hostname of MySQL instance
dbHost: ""
# For use with DATABASE locale resolver: Port of MySQL instance
dbPort: 3306
# For use with DATABASE locale resolver: Username for MySQL authentication
dbUser: "i18n"
# For use with DATABASE locale resolver: Password for MySQL authentication
dbPassword: "qwerty1234"
# For use with DATABASE locale resolver: Name of Database for MySQL instance
dbName: "i18n"
# For use with DATABASE locale resolver: Name prefix for MySQL tables
dbPrefix: "i18n_"

Locale Resolvers

Unless you have installed a plugin that changes I18N's internal locale resolver programatically you can configure the locale resolver you wish to use yourself. Locale resolvers provide a way of resolving and / or updating the preferred language of any player. Per default you can use the following constants for the `defaultLocaleResolver` field inside I18N's configuration:

  • CONSTANT - The fallback locale will be returned for each and every player
  • DATABASE - Requires a MySQL database. Stores the preferred language of players inside a MySQL database. Might be slow.

I18N adds a single command to your server which is the `/language` command. If no arguments are given it will display your currently preferred language. If you specify an ISO639 language code as the command's
sole argument (e.g. en, de, fr, es, ...) it will try to change your preferred language. You will be notified of the attempt's result in your chat afterwards. Players will need the `com.blackypaw.mc.i18n.command.language` permission in order to be able to execute this command.

NEW in 0.5.0-SNAPSHOT:
Currently, there are two events: The PlayerSetLanguageEvent which gets called whenever a player has successfully changed his / her language and the PlayerLanguageSettingEvent which gets called whenever a player's client-side language setting has been detected or changed. You may listen to these events in order to get notified whenever you should resend certain components such as scoreboards as they require you to manually resend them so that the player will get to see them in his / her new language.

User Translations

When using the `/language` command you might have noticed that it can be displayed in different languages. Per default I18N ships with translations for English and German, i.e. all text it prints out may be translated
into any one of these two languages. If you wish to add your own language to the plugin you can always check out the .properties files inside the i18n-spigot/src/main/resources/translations folder of this repository's source tree. If you are done with your translation you can save the file into the plugins/I18N/translations folder of your server and name it appropriately (fr.properties, es.properties, ...). After you enable the `allowUserTranslations` option in your configuration you will see that the `/language` command will be displayed in your own language, too.

For plugin developers

If you would like to use I18N with your next plugin you can use the resources down below for further reference.

Maven Repository

In order to simplify your life there is a Maven Repository from which you may retrieve the latest builds. Simply
add the following lines to your pom.xml:

        <name>BlackyPaw Public Repository</name>


You may find up-to-date JavaDoc pages here: https://www.blackypaw.com/docs/i18n/

Translation Storages

I18N ships with two built-in translation storages which allow you, to organize your translation in either .properties or .yml files.

Example of .properties translation files:
myplugin.greeting = Willkommen auf diesem Server!
myplugin.command.debug = Das ist eine Testnachricht!
myplugin.greeting = Welcome on this server!
myplugin.command.debug = This is a debug message!

Example of .yml translation files:
myplugin.greeting: Willkommen auf diesem Server!
myplugin.command.debug: Das ist eine Testnachricht!
greeting: Welcome on this server!
debug: This is a debug message!​
Both formattings of the above .yml translation files result in the same translation keys. Thus, feel free to use whichever format you like best.

Example Usage

Please see the README file of the project's GitHub repository (link below) for an example usage.


The project is licensed under the BSD 3-Clause license found in the LICENSE file in this source tree's root directory.


Found a bug? Can't get it to work on your server? Feel free to create an issue on the project's GitHub repository.

Please keep in mind that this resource is still work in progress and might contain some bugs. If you should encounter any such I would be please if you could drop me a message so that I can fix them.


GitHub: https://github.com/BlackyPaw/I18N
JavaDoc: https://www.blackypaw.com/docs/i18n/
Download / Maven Repository: http://repo.blackypaw.com/#view-repositories;public~browsestorage

Latest updates

  1. Update to Version 0.7.0-SNAPSHOT: Compatibility with Minecraft 1.10.2

    Updated to Minecraft version 1.10.2. Due to changes in Minecraft's network protocol this version...
  2. Update to Version 0.6.0-SNAPSHOT: Added support for translated display names of ItemStacks

    This new version allows you to translate the display names of ItemStacks so that each player...



First release
Last update
0.00 star(s) 0 ratings
You need to upgrade!
Our dark style is reserved for our Premium members. Upgrade here.