“Localization of Daisho Theme” Documentation by “Flow” v1.0

“Localization of Daisho Theme”

Created: 30/08/2012
By: Flow
Support Forums: Support Forum

This is Localization Guide for Daisho WordPress Theme. Localization support and WPML integration were added to Daisho in v1.7. Thank you for purchasing this theme!

Table of Contents

  1. Before We Start
  2. Localization Starter Package
  3. Introduction
  4. Picking the Right Localization Option for You
  5. POEdit Tutorial
    1. Introduction to gettext()
    2. Creating .POT/.PO files
    3. Translating .POT/.PO files and using .MO files
  6. WPML Tutorial
  7. More Information (Sources, Credits)

A) Before We Start - top

Okay, let's make some things clear at the beginning:

  1. Estimated time and money you will need to spend on translating your website:
    • TIME: 3-5h on WordPress/WPML configuration, 3-5h on theme translation alone (+ more on content).
    • TIME: Full gettext() manual is 300 A4 pages long. Resolving language-specific and technical issues may take some additional time.
    • MONEY: If you don't want to use WPML and you'll go with some other plugin or no plugin at all - free. The cost of WPML Plugin is $29 or $79 depending on version (we use $79 one and I think you need this one, too). One-year support is included in this price. The cost of having someone professionally and flawlessly setup all that for you would be around $250-$500, the cost of translating a single blog page is around $30.
  2. No demo content (.XML) or pre-made configuration file for multi-language website is available. You need to configure everything from scratch.
  3. Translating is very complex process for inexperienced users and might be also difficult at times for experienced ones. You will need to spend hours or even days on getting to know all that. Tutorials, videos, documentations, user manuals etc. have dozens of pages. WPML in some places is not well designed and it's not well documented (yet - it works just fine if you know how to use it). It is likely to cause confusion. And if you're new to WordPress and WPML - it may even be impossible for you to do it alone with your current experience and knowledge.
  4. Don't be scared though - 99% of website is easily translatable if you're average WordPress user. Problems may appear only with details.
  5. Internationalization of themes and plugins is still not widely spread, WordPress is very much English oriented. This means that difficulties in all languages that are very different from English are likely to appear.
  6. Localization is not a feature that we provide any support for. We can answer general questions but we are unable to spend hours on full localization of your website. To get help, you've got this guide, WPML Support Forum and we provide Localization Starter Package ($250) for agencies and those who need flawless and professional setup. All WPML help requests on support forum will be redirected to WPML support or moved to paid forum area unless they are general questions.
  7. You have access to information in this file before and after purchase. If you've made a decision to purchase this theme and localize it to your language then you agree to support policy for localization and you understand that it might be a problematic process for inexperienced users.

B) Localization Starter Package - top

Localization Starter Package ($250)

If currently available, one of our support staff members can help you setup fully working multilangual non-WPML or WPML-powered website for their hourly rate - $50/h. Cost of such help starts at $250 which covers 5 hours of work - the time that is generally required to install and configure WPML on your website by one of our support staff members and answer all your potential questions about localization.

WPML Plugin Support is also available to help you but they will not setup anything for you. They will only guide you through installation and configuration. The cost of their plugin and support is $29 or $79 (you need $79 version).

This is rather addressed to agencies or people who would like to outsource theme setup directly to developers. This is a good choice if you'd like to avoid frustration, you're busy or you're running some agency that simply needs website with WPML configured but you don't want to spend hours reading this and other guides, trying to configure WPML, WordPress and translation files.

Localization Starter Package covers (our support staff member will go down the list and complete the following in exactly presented order):

Green color indicates what we leave up to you - we will send you files to translate. Everything else will be done by us.

So, here's your choice: use Localization Starter Package or continue to setup above yourself with our guidelines below (the time it will take: 1 day or 5-10h).

If you don't need full package (let's say you only have problems with single, minor things) we can still resolve them for our standard hourly rate or you can try WPML Support Forum (recommended). We don't guarantee our availiability to help you.

C) Introduction - top

Internationalization (I18n) and localization (L10n) are means of adapting computer software to different languages, regional differences and technical requirements of a target market. Internationalization is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes. Localization is the process of adapting internationalized software for a specific region or language by adding locale-specific components and translating text.

- Source Wikipedia (Internationalization and localization)

Introduction

The theme files are Internationalized - they have been prepared for translation. This means that every single string in front-end and back-end (admin panel) is marked as translatable. Those strings can be used to create .POT/.PO file. .PO files can be created using stand-alone software like POEdit or using plugins such as WPML. .PO file contains a list of all strings. It enables you to add translations, save .PO file anytime, load it, add more strings (synchronize with theme files once again), edit previous strings and each time you do such work you can generate .MO file (using .PO file). .PO file will remain your working copy (that you can edit anytime) and .MO file is the one that WordPress will load when you put it into /languages/ directory.

Pages, posts, menus, categories, slugs, date format, widgets, custom fields in posts and pages and other similar things are not a part of theme but a part of WordPress. Theme translation functions and files have nothing to do with them. It's up to your translation plugin to translate that. Please note that not every plugin will allow you to translate every single part of your website. Some plugins may not allow you to translate for instance menus, slugs or categories etc.

Difficulties when translating

You can translate 99% of your website with ease. This includes menus, posts, pages and most of the WordPress-specific and theme-specific strings. However, there are many problematic areas such as:

You can use translation plugin of your choice, however, we do not guarantee that it will work with every single part of WordPress and that it will allow you to translate everything the way you want it.

The theme is WordPress multi-language (WPML) ready. WordPress multi-language is a plugin for WordPress that can be downloaded at http://wpml.org/. It is no longer free plugin and you'll have to purchase its copy in order to use it (you need $79 version - it has useful "String Translation" extension included). It's only useful for you if you'd like to translate your WordPress and have language switcher. You do not need this plugin if you'd like to have your blog in one language only (either English or other language). If you'd like to translate your website from English to other language and you're not planning to have language switcher then you do not need this plugin. You can just use .PO file to generate .MO file in your language. Plugin is not necessary in this case. Once again: plugin is only necessary if your website is supposed to have language switcher and multiple languages at once.

My personal opinion about WPML would be that this plugin is technically good and complete (it allows you to translate almost everything) and most importantly they provide good and quick support and that's basically all you need. Support is especially important here because you're likely to encounter problems or have questions - translation process is complex. I think that WPML is worth the price just because of the support and help you get from those guys. Theme developer (which is us) will redirect you to WPML documentation and WPML support if you encounter problems. We feel only responsible for delivering language switcher and theme files that are translation-ready. Working with WPML plugin (which is a complex plugin) is up to you. You will certainly need to check its FAQs and documentation several times - and translation may take hours!

D) Picking the Right Localization Option for You - top

Let's take a look at some translation cases. Please note that you actually need WPML only if your website is supposed to have multiple languages at once.

What are you looking for? Solutions
Case 1 Website in English only. N/A
Case 2 Website in English only + replacing existing strings like "All works" with something else.
  1. Do changes like that directly in template files (not recommended) or
  2. Create alternative English translation files (.PO/.MO) using POEdit or plugins. Second would be recommended but it would be also more complicated and time-consuming. By choosing second option you will be able to update the theme without losing your translation changes later on.
Case 3 Website in X-language only (non-English).
  1. Download WordPress in your language or enable your language in wp-config.php.
  2. WordPress will load its translation files from wp-content/languages/.
  3. Theme will load .MO file (based on WordPress language) if .MO file exists in wp-content/themes/daisho/languages/ folder. You need to create it for your language. If you prefer not to create it - you may do language changes directly in template files but it's not recommended because you will not be able to update theme later on.
  4. You don't need any plugins.
Case 4 Website in X-language only but you'd also like to use the theme for another website that is in either X-language or Y-language (separate WordPresses). If you're planning to use the theme on two separate WordPress installations then "Case 2" and/or "Case 3" apply to each one.
Case 5 Website in X-language and Y-language with language switcher. You'll either need WPML (theme has built-in language switcher) or other plugin.

E) POEdit Tutorial - top

Here's the short POEdit tutorial. Daisho already comes with POT file and Polish PO file, so first steps are just to provide some introduction. Follow them only if your POT file isn't up to date and you need to re-synchronize it with theme files.

Introduction to gettext() - top

Let's assume that we don't have any language files, yet for our theme but theme strings are put in localization functions. The complete list of localization functions that you can put theme strings in in WordPress v3.4.1 is here:

If any of theme files contain _e('string', 'flowthemes'); then the word string will show up on your website but it is also assumed a string ready for translation. It will be recognized by POEdit and WPML as something that you can translate. This function will replace string with its translation if available in .MO file that we'll create in a minute. Flowthemes is just textdomain that this theme uses. It's used merely to distinguish it from plugins or WordPress files - it's like context of strings.

It's the same with all other functions above. Differences between them are minor. For instance __(); is used in other PHP functions to return value rather than print it. _x(); and _ex(); are used to return or print string but they allow third, optional, parameter called "context" which simply tells translators what is the context of this string. In English you may have "Add Item" expression in many places on your website like "Add Item" to cart on front-end or "Add Item" to Slideshow in back-end. Context allows developer to put a note to translators on where does string appear on actual website which makes translations easier.

The last interesting function is _n(); which allows you to specify single and plural form of a word. Like "One Comment" or "Two Comments" and a number like: _n("One Comment", "%s Comments", $count, "flowthemes"); where $count is PHP variable that will be replaced by number and will be put in place of %s.

POT file contains a map of strings without translations. It is used to create PO file. PO file is the same what POT file but it contains translations for one language. Creating PO and POT files works exactly the same way. The only difference between them is extension and that the POT file should not have any additional meta data put in header. Both file can be edited using either POEdit or your favourite text editor. Theme developers usually scan their files using POEdit application and generate POT file (like daisho.POT). Then translators are able to create daisho-pl_PL.PO out of it and put there translations in one language only. If you need two languages then you create second PO file. PO files are used to create MO files. MO files are the ones that WordPress reads. POEdit should generate them each time you save your working copy which is PO file. MO files should be named using language code and country code like: pl_PL.MO.

Step 1 - Creating .POT/.PO files - top

Open up POEdit. If you wish to create POT file go to [File > New Catalogue]. If you're planning to generate your PO file out of POT file that we deliver, you will need to go to [File > New Catalogue from POT file]. In both cases you will need to setup the same settings but POT file should have metadata from this step left blank where possible. All the options on my screenshot below should be obvious except Plural Forms. Some languages have multiple plural forms (such as Polish - 2 or Russian - 4). More information on that can be found here: http://www.poedit.net/trac/wiki/Doc/PluralForms. If your language uses multiple plural forms then you'll need to come up with formula describing this. Examples:

Step 2

Go to "Sources paths" and use ../ in the first field and . in the second (or vice versa). Dot means that it will start looking in the current directory. Please note that this is not your HDD path nor anything like that. It's a path relative to /languages/ directory in theme folder. So, we first need to go up one directory and then start indexing files. This should be set like that whether you create POT or PO file.

Step 3

Go to "Sources keywords" and add all functions that it should look for when scanning theme files. Please note that I used _n:1,2 to indicate that there will be multiple plural forms for this language. What this will do? It already knows that we use 1 Comment and 2 Comments in English because we used this: _n("One Comment", "%s Comments", $count, "flowthemes"); in comments.php file but it will also add three new forms as translation: single, plural_1 and plural_2. It will distinguish them automatically after creating .MO file if you setup correct formula in step 1. If your language has one plural form then it should be just _n. This is important to be set like that for PO file. POT file can have those functions added, too. It will make it easier to generate PO file for translator if you list all possible localization functions in POT file.

Step 4

Click OK. It will ask you to save .PO file, so pick /language/ directory as place to save it and name it like: daisho-pl_PL.po where first 'pl' is language code and second 'PL' is country code. If you have not set any plural forms and additional metadata you can also rename it to daisho.pot because it's going to be a good base base file to create more .PO files. Like I said at the beginning we already created empty .POT file for you, so you don't have to do it.

Step 5

If you followed steps 1-4 to create POT file (rather than PO one), please go to [File > New catalogue from POT file] and open up your or our .POT file. It will instantly want to create .PO file for you, so please start from step 1 to setup it if you haven't done that, yet.

Step 6 - Translating .POT/.PO files and using .MO files - top

Once you have .PO file for your language you can start translating theme in POEdit. Save your changes anytime or hit "Update" to synchronize it with theme files. Once again name your PO file: daisho-pl_PL.po and MO file should be named: pl_PL.mo for themes. PO file is your working copy that you can edit anytime. MO file is the one that POEdit will generate for you each time you save your project. If pl_PL.mo is located in /languages/ folder and you set pl_PL language in wp-config.php it will no longer load English strings. It will load Polish strings if available (if not it will use English ones).

Conclusion

So, that's everything about POEdit and POT, PO and MO files. Using POEdit alone will allow you to deal with "Case 2", "Case 3" and "Case 4" in my Picking the Right Localization Option for You table. That's where our tutorial comes to an end. You can use WPML to deal with "Case 5".

F) WPML Tutorial - top

Here's the short WPML guide for "Case 5". It is just brief overview and not something you should follow. Please see Sources and Credits section to access WPML guides. They are more complete and helpful. Please contact WPML Support to get localization help. They have Daisho installed on their server. You can also use our Localization Starter Package to have one of our support staff members setup that for you. So, here are some steps:

G) More Information (Sources, Credits) - top

Here are some useful links and information:

Thank you for reading this document. If you have any questions relating to localization feel free to ask them on support forum. No guarantees, but I'll do my best to assist.

Flow on ThemeForest (follow)

Go To Table of Contents