LanguageAPI

LanguageAPI is a tool for plugin developers to internationalise their plugin to make it simple and easy to translate into any language. Please note: This is not a translation plugin, it is a tool to assist human translators and plugin developers. This is not a standalone plugin, it will not do anything by itself, it is a tool for plugin developers to include in their projects.

If you are a plugin developer, and you want to expand your user-base to include other languages, this LanguageAPI provides a simple, easy and effective means to do so. All you need to do is include the LanguageAPI jar as a library in your project and you can start to use its features.

If you would like to see another plugin in a different language, you could contact the author and politely suggest that they could use this API, as it would make the task a whole load easier for them.

The basic idea is that every string that is ever required from or displayed to a user is separated from the hard code in a lang-???.yml file (where ??? is your default locale ISO code). The default lang-???.yml file will be automatically generated during testing, and can then be translated into other languages. International or multi-language users can then download any lang-???.yml files of their choice to use with the plugin and after player's set their personal locale, messages from the plugin will be translated to that language, quickly, efficiently and without any recompilation necessary. Although international or multi-language users would also need to install the LanguageAPI with your plugin, it is a small price to pay to be able to use your plugin in their own language.

You may be asking, why use an API plugin when I could write something like this myself and add it to my plugin? Well, you certainly can do that, and so can everyone else. This will lead to situations where players need to set their locale for every single international plugin on a server, and some servers have 20-30 plugins or more. Very irritating for them, I am sure you'll agree. Now imagine a number of plugins start using the API and yours is one of the few that doesn't. Players can then set their languages for the whole server, and then find that they have to set it again just for your plugin.

I have also provided a wrapper class for the API, which checks to see if LanguageAPI is installed, and if it is not, uses the default translation. This means that you can soft-depend the LanguageAPI plugin and your local language users will not even need to install the LanguageAPI to use your plugin, which should avoid inconveniencing users who don't need any translations.

• Simple and easy to use
• Minimal code changes needed to update an existing project to use LanguageAPI
• Well-documented API methods
• Supports multi-language servers
• Provided a wrapper class so you don't need LanguageAPI as a hard dependency if your users don't require translations
• Automatically creates your default lang-???.yml file for your own locale from your own code during alpha testing
• Uses message templates to handle strings that need to have dynamic data entered into them
• Allows complete customisation of these message templates for translation into other languages
• Uses efficient string concatenation algorithms to compile the display string from templates
• Robust error-handling, reverts to using the default language when there are errors in a particular lang-???.yml

• This plugin does not magically translate your plugin into all known languages, it still requires translators to modify the lang-???.yml files into different languages
• It only works for plugins that are written specifically for the LanguageAPI, you cannot just drop it into your plugins folder and expect it to translate completely unrelated plugins
• It does not find all of your output strings for you and put them into the lang-???.yml, you have to call the language library every time you use an output string
• It does not translate in-game chat messages or text in books or signs created by players
• It currently does not provide support for translating the Bukkit help system for commands and permissions into other languages, however it may do so in the future

If you have been sent here from another plugin, all you need to do is download the LanguageAPI.jar and place it into your plugins folder. You should be able to obtain the language.yml file for your desired language from the plugin that directed you here.

Download the LanguageAPI.jar from Bukkit: http://dev.bukkit.org/server-mods/languageapi/files/6-language-api-v0-2/

If you want to include language support in your plugin, you will need to download LanguageAPI.jar and include it as a library for your project. To start using it, you can create a new Language object using your plugin as the only parameter. This Language object can then be called to get the localised string for the given key, and also defines the default string template.

Download the LanguageAPI.jar from Bukkit: http://dev.bukkit.org/server-mods/languageapi/files/6-language-api-v0-2/

International and multi-language users will also need a copy of the LanguageAPI, please direct them to this page so they can obtain the latest version from the official author.

For detailed help for developers, see the Developers page.

In order to translate a plugin that uses LanguageAPI to another language, you should obtain a copy of the default language.yml file for that plugin. They should provide this to you on their page, or on request.

The format for the file is actually a stripped down version of YAML, which does not contain all of the reserved characters which would normally make translations a pain, so you will not need to worry about this. It is in the following form:

key: template text interspersed with {number}

You must leave the keys exactly as they are, untranslated. These are not displayed anywhere, they are just used by the plugin to determine which string template to use. Instead, you should translate the template text only.

The curly braced numbers refer to dynamic data that is added to the strings while the plugin is running, e.g.

player-slain: {0} was slain by {1}

Where {0} is replaced by the player's name, and {1} is replaced by what or who has slain the player.

You can rearrange these as much as you want, even use multiples of them, e.g.

player-slain: {1} has slain {0}. Bad luck for {0}!

However, you cannot create new ones, only use existing braced numbers.

Help translate the LanguageAPI plugin

If you would like to help translate the LanguageAPI plugin itself into other languages, please see the Languages and Translation page. While at least one of your translations is currently in use, your BukkitDev profile will be displayed as a Translator for the project.

You can find a list of Translators here.

This list is provided for your convenience only and should be used at your own risk. This should not be considered an endorsement; we cannot verify the quality of translations nor do we vouch for their authenticity or mediate disputes. If you use this list, you take full responsibility for anything that may result from its use.

If you are a translator, and would like to be added to this list, please contact me via private message or leave a comment, and state which languages (and ISO codes) you are able to translate to and from.

This plugin uses Java 7

If you get the followed error on starting up the server with this plugin installed "Unsupported major.minor version 51.0". This means you are using an out of date version of Java. If you don't know how to upgrade, please contact your server hosting provider and ask them for help in upgrading to Java 7, or contact Oracle customer support. Mac OS X users require JDK 7 instead of JRE 7.

If you'd like to contribute towards the continued development, support and maintenance of this project, please consider joining me on Patreon, and making a one-time or recurring pledge.

If you need help you can leave a comment below and I will get back to you as soon as I can. You can also join my IRC chatroom using the following link. Please note, I am not always at my keyboard! http://webchat.esper.net/?channels=XHawk87&prompt=1