[Tutorial] Languages File

Having a languages file for you plugin can be useful for you (the plugin developer), and the end user of your plugin. A language file (aka a Captions file) allows you to change all of the strings in your plugin easily, without messing around with code. This helps you, as you can perfect chat messages after finishing your plugin, and it helps the end user, as they can customise it to fit their server (heck, they can even change the language!). In this tutorial, I'll be showing you how to create a class to handle a custom language file.

Our language file will because lang.yml, and we are using the YAML format just for ease-of-use (Bukkit has a built in parser). By the end, our lang.yml will contain text like the following;

Code:text

MsgNotEnoughMoney: '&cHey, you don''t have enough &a$$$&f!'
MsgPaymentCompleted: '&aLooks like that payment has completed!'

So, let's get started with our caption handler. This tutorial expects you to know at least basic Java, and it would help to be familiar with the Bukkit API.

Code:java

package me.jackwilsdon.gconomy;
 
import java.io.File;
import java.io.InputStream;
 
import org.bukkit.ChatColor;
import org.bukkit.configuration.file.FileConfiguration;
import org.bukkit.configuration.file.YamlConfiguration;
import org.bukkit.plugin.Plugin;
 
public class CaptionHandler {
private Plugin plugin = null;
 
private File configFile = null;
private FileConfiguration config = null;
 
public CaptionHandler(Plugin plugin)
{
this.plugin = plugin;
this.configFile = new File(this.plugin.getDataFolder(), "lang.yml");
 
this.reload();
this.saveDefault();
}
 
public void reload()
{
this.config = YamlConfiguration.loadConfiguration(this.configFile);
 
InputStream defaultConfigStream = this.plugin.getResource("lang.yml");
if (defaultConfigStream != null)
{
YamlConfiguration defaultConfig = YamlConfiguration.loadConfiguration(defaultConfigStream);
this.config.setDefaults(defaultConfig);
}
}
 
public void saveDefault()
{
if (!this.configFile.exists())
{
this.plugin.saveResource("lang.yml", false);
}
}
 
public String getCaption(String name)
{
return this.getCaption(name, false);
}
 
public String getCaption(String name, boolean color)
{
String caption = this.config.getString(name);
if (caption == null)
{
this.plugin.getLogger().warning("Missing caption: " + name);
caption = "&c[missing caption]";
}
 
if (color)
{
caption = ChatColor.translateAlternateColorCodes('&', caption);
}
return caption;
}
}
 

So, let's go through this class line by line. First of all, we simply create a few variables that hold our plugin reference, along with configuration information. Next up, we set up a constructor for the class, that allows for the class to take an instance of the plugin to use. Inside the constructor, we set the plugin instance, as well as creating the lang.yml file and running the reload() and saveDefault() methods we will look at after.

Now comes the reload() method. It's a lot less complex than it sounds, it just loads the YamlConfiguration using Bukkit's built-in class, but also creates and loads the defaults from the lang.yml inside out plugin. Our saveDefaults() method is even simpler. It just checks if the lang.yml exists, and if not, writes a new lang.yml file there from inside our plugin. Finally, we have our getCaption() methods, which I will explain below.

We have 2 getCaption() methods, of which one calls the other. This is called method chaining, and can be useful under certain circumstances where you want 'default' arguments. In our case, we use it to say "unless otherwise specified, we want our messages in color". Our second getCaption() takes a name in for an argument, similarly to the first one. This one however actually manages the captions themselves, in a similar way to the default Bukkit configuration API. We simply get a string from the config file, and if color is true, then we translate the alternate color codes into chat colors.

And that's it really. You can use our newly created class as follows;

Code:java

CaptionHandler handler = new CaptionHandler(this); // 'this' must be replaced with a JavaPlugin reference when used from any other classes.
System.out.println(handler.getCaption("MsgPaymentCompleted"));

I hope you found my first tutorial useful, and if you have any questions, please don't hesitate to ask here or PM me