Friday, December 5, 2014

Wordpress: Using Poedit to translate your site

When you make a multilingual website, you can use a plugin like polylang to translate your content, but certain elements that are hardcoded into your theme files will not be translated. For these you will have to use Poedit to make the translations.

1. Prepare your site

First of all you have to prepare your theme to accept your theme-specific expressions by inserting this into the top of your functions.php file:

 load_theme_textdomain( 'theme_name', TEMPLATEPATH.'/languages' );  

2. Convert your hardcoded expressions

In your theme php files find all expressions like "Search", "No posts found" and such and convert them to use the __() or _e() wordpress functions. The difference between them is that _e() immediately prints the expression while with __() you can do more complicated things too.

For example conver this:

 <a href="#">Search</a>  

To this:

 <a href="#"><?php _e('Search', 'theme_name'); ?></a>  

Or:

 <?php echo '<a href="#">'.__('Search', 'theme_name').'</a>'; ?>

3. Get Poedit

Dowload and install Poedit. If you are using Ubuntu, type this into the terminal:

 sudo apt-get install poedit  

4. Process your source

You need your theme files on your local machine, so if you are working on a remote server, copy the whole thing down to your machine somewhere.

Start Poedit and create a new .pot file by clicking on File > New. In the pop-up window put your theme_name in the first field (project name and version) and choose utf-8 for the source character encoding.

On the next tab, click on the new element icon and add "." to the paths. On the third tab add "_e" and "__" to the list of keywords.

Press Ok to save your file and save it into the theme directory with the theme_name.pot filename. Poedit will also save a .mo file too, just leave that be.

With this we created a catalogue of expressions that our site uses that will be the basis for our language files.

5. Create the language variants

To my experience it is better to completely close poedit and open your files again as some bugs can make your life very hard otherwise. Just keep that in mind :-)

Close Poedit, start it again and open your .pot file. (You will have to choose *.* in the open file dialog.) Click File > Save as and save versions for your languages with the proper language codes. In my example I needed an english, a hungarian and a german version, so I named the files:

en_US.po
hu_HU.po
de_DE.po

These are your work files, that will be used for the translations. If you developed your website in english, you will not have to edit the en_US.po file at all, as it already contains all the expressions in english that you used in your sources.

Poedit also saves a .po version of these files. They are the machine readable translations that Wordpress actually uses. You cannot directly edit them, you will edit the .po files only.

6. Translate your expressions

Open up your .po files and fill in the proper translations. When you are finished, click save. Poedit will save the file and also the .mo version.

When you are finished with all the languages, upload ALL .po and .mo files to the /languages directory of your theme on the live server. (If you are working locally, just move them there). You will store the catalogue and the language files there too.

Test your site, your expressions should now be working.

7. Adding new expressions to the language files

If you need to add new expressions, just add them to the source as you did in point #2. When you finished development and need to add the translations. You will have to copy your theme directory again to the local machine (if you develop on a remote server) and move the language files to its root.

You have to open the .pot file and click on Catalogue > Update from source. Save and the new expressions are now in the catalogue.

You will also have to open up the language .po files and click on Catalogue > Update from POT. Now the new expressions are in the language file, you can make the translations. Save it and upload all language files back to the server to the theme's /languages directory.