Tuesday, March 6, 2012

How to Translate a WordPress Theme

If you are familiar with WordPress and the many plugins and themes available for it, you’ve probably come across some strangely named files like .mo, .po, and .pot. If you haven’t then the theme and/or plugin has not been designed for translation. This article explains how to take a .po file that is included with your WordPress theme and/or plugin download and translate it into your native language.
Don’t have a .po or .mo file for your theme or plugin yet? Follow these steps on how to generate your first WordPress .pot file. Another good article with resources about how to translate WordPress into your language is located here.
So what the heck are those .mo, .po, and .pot files anyhow and why are they included in my download?
Well, the files aren’t really important if English is your primary language but if you want to have WordPress, a WordPress theme, or even a plugin localized in your native language then those files are golden.
  • .mo stands for Machine Object
  • .po stands for Portable Object
  • .pot stands for Portable Object Template
The file that you want is ideally a .po file since it’s the raw editable text scraped from the entire WordPress theme/plugin. The .mo file is the compiled export of the .po file which is used by WordPress.
Here are the steps to translate/localize a .po or .pot file into another language
  1. Download a gettext file editor like poedit and install it.
  2. Open the English .po file that came with your WordPress theme or plugin with poedit. If you only got a .pot, just rename it to .po and open it in poedit.
  3. Now go through and translate all the text one line at a time in the bottom box.
  4. Then “File” => “Save as” to your desktop or a folder on your computer. This will output a .po and .mo file.
As you can see from the screen shot below, the top part of the file contains the entire list of text that needs to be translated. Each line represents a place within the WordPress theme or plugin that stores the text. If you click on different lines, you’ll notice the section below displays that exact line of text. What’s even cooler is if you right click on any line, you’ll see a file name and line number like “comments.php line 121″. That is the exact place in the theme or plugin where this text is being used.
poedit-usage
Now here’s where you need to pay attention. The blank box below that is where you will type in your translations. So in the screen shot I translated “Page not found” into Spanish by typing in the correct translation in the box below.
Important Note: Some text characters need to be converted into html entities otherwise they will not display correctly. A very common example is a word containing an apostrophe or single quote (‘) which needs to be replaced with ' — for example, Chloe O’Brian should be written as Chloe O'Brian. Kind of strange I know but that’s just how the parser works. For a complete list of html entities, visit W3Schools.
One other thing worth mentioning. PoEdit might give you an error related to “% comments” while you try to save the file (usually when you have a K preceding it like in German, “% Kommentare”). Usually if you just ignore the error, it will save fine. I will try and fix that comment translation issue in the next release.
After you start making updates, you’ll notice the upper right portion of the file will begin to fill in. Once you finish the translation (make sure to save often), you will have your final raw file.
Now that you’ve completed your translations, you can plug-in your file and see if it works. The .po file is your editable file which you can always load back up in poedit and update. The important file is the .mo file. This is what WordPress will use and if it’s for a new theme like ClassiPress, it needs to be placed in the /wp-content/themes/classipress directory.
I also forgot to mention that the naming of your .mo files is very important and must match the desired locale otherwise it won’t work. The naming convention is based on the language code (e.g. pt for Portuguese) followed by the country code (e.g. _BR for Brazil). So, the Brazilian Portuguese file would be called pt_BR.mo. See the complete list of language codes and country codes to find your exact locale.
You will also need to make a change to your WordPress wp-config.php file (located in your WP root directory) with the correct language codes like the example below. If you don’t have a WPLANG entry then create one.
define ('WPLANG', 'pt_BR');
Assuming you’ve made all these changes, you should now be able to reload your WordPress theme and see it in your native language! If it’s not working, chances are you didn’t use the correct naming conventions for your .mo file or in your wp-config.php file. If you see part of your site translated you either didn’t translate the entire .po file or the .po file wasn’t completely translated correctly in the first place.
So if you recently purchased ClassiPress and a language pack file (.mo) is not available for your native language, you should follow the steps above and create your own. ClassiPress is designed to work with virtually any language so just take the included .po file and translation away! Make sure to contact us and send over a copy so others can download your language pack. You will get full credit for the work and a link back to your site in return.

How to Update an Older .POT File

If you’ve previously translated an older version of ClassiPress and upgraded your site to the latest version of ClassiPress, you’ll notice the translation file no longer works correctly. This is due to the fact that the ClassiPress code has changed and the old .mo language file can no longer find the text locations.
Before I explain how to update your old language file to include the latest text to translate, I wanted to go behind the curtain and show you how it works. The .POT file is essentially a mapping of which text should be replaced in what file. It keeps track of this by file names and line numbers. When the ClassiPress code changes, it moves the line numbers so the .MO file can no longer find the original text to translate. To better understand what I’m talking about, open the .POT file with a text editor. You’ll see a bunch of readable lines that look like this:
#: 404.php:24
msgid “Whoops! Page Not Found.”
msgstr “Whoops! No se pudo encontrar la pagina.”
The first line tells the language processor what file (404.php) and line number (24) the text to be translated is located on. The “msgid” is the actual text that needs to be translated and the “msgstr” is the new translation (in this case, Spanish). Pretty easy once you understand how it works, huh?
Ok, so let’s talk about how to update your old ClassiPress.POT file.
  1. First open your old existing translated .POT file (i.e. pr_PR.po) in POEdit. “File” => “Open”
  2. Next you’ll need to compare it with the new .POT file. Do this by going to “Catalog” => “Update from POT file” and select your new .POT file.
  3. Now PoEdit will show you what text is new and needs to be translated. It should also update any other changes that have been made.
  4. After you have translated the new text, save the project and then it will create your new .MO file.
  5. Overwrite your old .MO file in your /themes/classipress/ directory and look at your site.
  6. Also make sure you’ve activated the latest version of the theme (the one that the new language file came with)
Now that should be it. Once you know how to work with existing .POT files, doing the updates can be really easy. Source: http://www.appthemes.com