Plugin translation has never for me seemed an easy task, i could never quite follow the mish mash of differing information around the web, and none of the guides available ever seemed to answer the specifics of what i needed to know about setting up a plugin for translation.
Well a couple of months have passed since i last put my head down and read up on the translation process, and fortunately for me the persistance in grasping the technique has paid off, i’ve managed (well i hope) to grasp the fundamental points of how to prepare a plugin for translation, and additionally how to run through a translation process.
Those of who would just prefer to see example code can skip straight to the plugin download.
NOTE: This is intended for code literate users, those of you who can already code but just need a quick run down on how to utilise the translation functionality inside a plugin.
Firstly your plugin will need to register a text domain for performing translation tasks, you can read more on that here. Of course the codex entry does leave a little to be desired, not really giving much in the way of an easy to follow example.
However, let’s just run by the parameters for load_plugin_textdomain very briefly.
This is basically the name for your text domain. You’ll have to reference this alot in your plugin, so it certainly helps to make it something easy to remember and quick to type. The name (or domain) declared here will also prefix all translation files used in your plugin, so do try to KISS.
We will ignore this parameter because it’s no longer used as of WordPress 2.7, originally you would use this parameter to declare the path to the language files in your plugin, based on the WordPress ABSPATH. I will not be using this parameter for the example, so i’ll stop there.
I think the codex description sums up what this parameter does pretty well (not perfect though).
Relative path to WP_PLUGIN_DIR. This is the preferred argument to use. It takes precendence over $abs_rel_path
Ok, so now the description is out of the way, where should you place the call to load_plugin_textdomain?
As far as i know textdomains should be registered at the init stage, so depending on whether you want to translate front side, admin side or both, will depend where you hook the registration onto, but for the sake of this example i’ve hooked mine onto admin_init.
Inside the main function of my plugin class is a line like so.
// The action hook add_action( 'admin_init' , array( &$this , 'register_plugin_settings' ) );
Various other pieces of code are present in the functions, so to keep this blog trim here’s the line inside the above referenced function that registers the textdomain.
// How the text domain looks inside the register plugin settings function referenced above load_plugin_textdomain( $this->l10n_prefix, // Plugin text domain reference false, // False - deprecated parameter basename( dirname( __FILE__ ) ) . '/lang' // Path to translation files );
In the case of my example plugin(at the end of this post) i’ve used a variable to store the name of the textdomain, this means i don’t have to keep remembering the reference name, i simply type in the variable each time i want to make some text translatable.
More information and a very similar example of load_plugin_textdomain can be found here.
Here’s my text domain variable for reference.
$this->l10n_prefix = 'translatable_demo';
Also note the third parameter used in the text domain registration, this sets where to look for the translation files, you can however (as the codex entry suggests), leave this blank and WordPress will assume they reside in the same folder as your plugin. Of course it’s good to keep things organised, i know i do(just a little), so i’ve opted to have the text domain reference a folder called “lang” (no quotes) inside my plugin’s folder.
Ok you’ve come this far, you’ve registered a text domain, what next?
Next you’ll need to start converting all the strings in your plugin you wish to make translatable, and this is probably the most easiest step in the whole process, and rather then repeat the guides and information already available i’ll simply point you here, and provide a very brief example below based on my example plugin.
$var1 = 'WordPress'; echo 'Hello world';
Translation ready: (remembering the text domain name)
$var1 = __( 'WordPress', 'translatable_demo' ); // __() return value _e( 'Hello world', 'translatable_demo'); // _e() - echoed value
That’s it as far as making the plugin translation ready, honestly, what more did you expect?
Techinically there is nothing left to do on your part, the plugin can be translated, but a good practice for plugin developers (or so i hear) is to include a .POT file along with the plugin. In the most simple terms this is a base translation file, that will in essence be like any translation of your plugin, but not include a translation for each string, providing a .POT file just means a translator can pick up that file and get translating without having to run your plugin’s folder/files through a translation program (you save them a few minutes, but it’s really very easy, and the process is pretty much identical to that of the translator).
For those of you still interested in learning how to create a .POT file and developing language files read on, i’m going to run down the procedure i followed for creating a .POT file. I’m a windows user, so those of you on another OS, you’ll unfortunately have to look toward existing guides on how to translate. Anyone still with me, read on..
- Download and Install Poedit (it’s free).
- Open Poedit and click on New Catalog, under File.
- Fill in a name for the project, and choose the appropriate language you write in (not required but i tend to do it anyway).
- Click on the Paths tab at the top of the box.
- Click the second little icon, and put the directory location of your plugin in, for example “C:\Documents and Settings\USER\Desktop\MY_PLUGIN”
- Click on the Keywords tab at the top of the box.
- Click the second icon, and enter “__” (no quotes, and that’s two underscores).
- Click the second icon again, this time entering “_e”
- Now click the Ok button.
- A save dialog will appear, so enter a name for your POT file and change the extension to .pot
- Choose an appropriate place to save the file (you’ll probably want to choose to the language folder inside your plugin).
- Click Save.
- Various things will happen now and poedit will shows some boxes on the screen. Don’t do anything, this is what a translator will see when he or she is translatin your POT file. Just close the file, job done.
NOTE: It’s most likely a good idea to name your POT file with the same prefix the translation files will require. The prefix is the name you gave you text domain inside your plugin, ie. the first parameter.
Doing translations is the easy part, so i’m leaving that out of my blog for now, but if anyone finds this useful and would like to see an additional “How to make a translation file” or similar, then post a comment, let me know.
If you struggled to keep up with anything covered above, or you think anything above could do with refinement, again feel free to provide feedback, i’m not the world’s best blogger, and my mind can wander when writing, so critique is most definately welcome..