- Tags
I18N
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.
Configuration
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: "127.0.0.1"
# 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_"
}
# 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: "127.0.0.1"
# 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:
Events:
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:
Code:
<repositories>
<repository>
<id>blackypaw-repo</id>
<name>BlackyPaw Public Repository</name>
<url>http://repo.blackypaw.com/content/groups/public/</url>
</repository>
</repositories>JavaDoc
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.command.debug = Das ist eine Testnachricht!
myplugin.greeting = Welcome on this server!
myplugin.command.debug = This is a debug message!
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!
myplugin.command.debug: Das ist eine Testnachricht!
myplugin:[/COLOR]
greeting: Welcome on this server!
command:
command:
debug: This is a debug message!
Example Usage
Please see the README file of the project's GitHub repository (link below) for an example usage.
License
The project is licensed under the BSD 3-Clause license found in the LICENSE file in this source tree's root directory.
Issues
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.
Links
GitHub: https://github.com/BlackyPaw/I18N
JavaDoc: https://www.blackypaw.com/docs/i18n/
Download / Maven Repository: http://repo.blackypaw.com/#view-repositories;public~browsestorage
