“Localization of Daisho Theme” Documentation by “Flow” v1.0
“Localization of Daisho Theme”
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
- Before We Start
- Localization Starter Package
- Picking the Right Localization Option for You
- POEdit Tutorial
- Introduction to gettext()
- Creating .POT/.PO files
- Translating .POT/.PO files and using .MO files
- WPML Tutorial
- More Information (Sources, Credits)
A) Before We Start - top
Okay, let's make some things clear at the beginning:
- 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.
- No demo content (.XML) or pre-made configuration file for multi-language website is available. You need to configure everything from scratch.
- 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.
- Don't be scared though - 99% of website is easily translatable if you're average WordPress user. Problems may appear only with details.
- 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.
- 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.
- 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):
- One additional language setup (+$100 for each next language),
- Installation and Configuration of Daisho and Typography Plugin,
- Installation of necessary WPML modules,
- Configuration of necessary WPML modules,
- Server Configuration (URL, .htaccess, CHMOD etc.),
- Language Switcher Installation and Configuration (header),
- (optional) Language Switcher in sidebar (not styled, only default style or without any style because theme doesn't contain styled sidebar language switcher),
- (optional) Language Switcher in footer (not styled, only default style or without any style because theme doesn't contain styled footer language switcher),
- (optional) "this post/page is also available in X-language" link at the beginning or end of each post or page (styled),
- Creation of correct .PO file for your language (with consideration of all language specific nuances),
- Guidance through translation (we prepare .PO file but you need to translate it into .MO file),
- Installation and configuration of .PO, .MO and PHP (containing exceptions) files for WordPress itself in your language (if available) - this includes admin panel strings, hard-coded front-end strings available in WordPress functions, network admin strings, all special cases of translations for your language and list of country names in your language,
- Preparing Posts, Post Categories, Post Tags, Post Custom Fields, Pages, Pages Custom Fields for multilangual use,
- Preparing Custom Post Types (Portfolio, News, Slideshow) and Custom Fields of those posts for multilangual use,
- Preparing Menus for multilangual use,
- Preparing Widgets for multilangual use (only using "String Translation" extension for WPML),
- Preparing Contact Form for multilangual use,
- Preparing Date and Time Formats to work in multiple languages ("String Translation" extension for WPML),
- Admin strings setup (and guidance through translation but you need to translate that yourself) ("String Translation" extension for WPML),
- We leave you with website ready for translation. You can enter it and edit your posts, pages, menus etc.
- We also help resolving common WPML problems such as double slash in URL: "http://example.com/pl//" or problems that arise when you translate less common things.
- We help resolving language-specific things and provide some information and guidance for unordinary things such as negative numbers forms, numbers formats, multiple plural forms in some languages, declensions, abbreviations etc.
- We will also keep in touch with you via email and work with you until you translate everything just the way you want it.
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)
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:
- Admin texts - in admin panel you'll often find textareas and input fields created by us (with exclusion of post/pages custom fields) that allow you to put custom text (such as footer copyright notice). This can't be translated using .PO/.MO files and majority of translation plugins won't allow you to translate that but WPML enables you to translate that using "String Translation" extension. Strings that apply to this exception: "welcome_text", "footer_copyright". They are marked as "admin_texts_theme_daisho" Context.
- Admin texts (select page - "Info Box", "Front Page" etc.) - in admin panel you'll find select boxes that enable you to pick page that will be displayed as front page. This can't be translated using .PO/.MO files and when you simply translate "Homepage" into different language it won't do the trick. Majority of translation plugins won't allow you to translate that but WPML enables you to translate that using "String Translation" extension. In "String Translation" you need to find strings such as "front_page" and put ID of different page as translation. This is tricky and might be not obvious for inexperienced users but that seems to be the only workaround. More strings that apply to this: "flow_blog_page", "flow_portfolio_page", "front_page", "info_box". They are marked as "admin_texts_theme_daisho" Context.
- Admin texts (WordPress Fields) - in admin panel you'll find WordPress fields such as Blog Title, Blog Description etc. This can't be translated using .PO/.MO files. WPML enables you to translate that using "String Translation" extension. In "String Translation" you need to find strings such as "Blog Title" and "Tagline" and translate them. They are marked as "WP" Context.
- Admin texts (Widgets) - in admin panel you have widgets under [Appearance > Widgets]. This can't be translated using .PO/.MO files. WPML enables you to translate that using "String Translation" extension. In "String Translation" you need to find strings such as "widget title" and "widget body" and translate them. They are marked as "Widgets" Context.
- WordPress Strings - they will be loaded from .MO files placed in wp-content/languages/. You need to download WordPress in your language, copy that folder and upload to your English installation of WordPress. WPML "String Translation" extension allows you to overwrite them with your own translations. Context is marked as "theme".
- Theme Strings - they will be loaded from .MO files placed in wp-content/themes/daisho/languages/pl_PL.mo (where pl_PL is your language code and country code). You need to create .MO file out of .POT or .PO file that we deliver in this folder. WPML "String Translation" extension allows you to translate theme strings directly in admin panel (however, I recommend translating them using .PO and .MO files using POEdit). Context is marked as "theme flowthemes".
- Some languages may have multiple plural forms of words. Example: 0 Comments, 1 Comment, 2 Comments (that's what you have by default in WordPress and English). But let's take a look at Polish language: 0 Komentarzy, 1 Komentarz, 2 Komentarze, 5 Komentarzy. You see that there can be two plural forms and that is different than in English. Editors such as POEdit allow you to specify number of plural forms for your language in .PO/.MO file but this requires you to code pattern as per their requirements: http://www.poedit.net/trac/wiki/Doc/PluralForms. WPML in version 2.6.0 doesn't offer ability to setup multiple plural forms. Please see my POEdit guide for more information. This is one of the reasons why you should use POEdit to prepare .PO/.MO before you use WPML.
- Post types are named as follows: 'post', 'page', 'portfolio', 'slideshow', 'news'. As for now this is not translatable and your URL will reflect it as: ?p=, ?page_id=, ?portfolio=, ?portfolio_category=, ?slideshow=, ?news= (unless archives are disabled - we disabled them for some custom post types). Attempts to translate that are not recommended.
- Date formats - we found this a bit problematic but fortunately only when using main WordPress .MO file to setup date - that fails to work sometimes (depending on theme files and context it may work or may not work). To make it always work you should translate them using .PO/.MO files if available (.PO file will contain something like 'F jS, Y' or 'F d, Y' which is date format). More information: http://codex.wordpress.org/Formatting_Date_and_Time
- Other Language exceptions - languages may have already mentioned multiple plural forms, different date formats, different number formatting, different plural forms for negative numbers, different structure of sentences, some may require you to adjust website from LTR to RTL text, some languages require that you expand charset of fonts used etc.
- Technical issues - many strings don't allow some characters like ', ", \, / etc. Using them may break the website. Also, you should not alter HTML in any way if given in string. Developer gave translators ability to see accompanying HTML just to better understand context. You should leave that in place.
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?
||Website in English only.
||Website in English only + replacing existing strings like "All works" with something else.
- Do changes like that directly in template files (not recommended) or
- 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.
||Website in X-language only (non-English).
- Download WordPress in your language or enable your language in wp-config.php.
- WordPress will load its translation files from wp-content/languages/.
- 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.
- You don't need any plugins.
||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.
||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
then the word
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
with its translation if available in .MO file that we'll create in a minute.
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.
_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
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:
nplurals=3; plural=n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
nplurals=2; plural=n != 1;
nplurals=3; plural=(n%10==1 && n%100!=11) ? 0 : ((n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20)) ? 1 : 2);
nplurals=4; plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
- More formulas: http://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html#Plural-forms
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.
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.
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.
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).
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:
- Install our theme on fresh installation of WordPress. Import sample content or configure your content. I assume you have fully working website in English at the end of this step.
- Buy WPML - $29 or $79 - you rather need $79 version because it contains "String Translation" extension - http://wpml.org/purchase/
- Install "WPML Multilingual CMS" (we use 2.6.0, August 27th 2012 on WordPress 3.4.1) - this is the core module that each WPML website needs.
- Install "WPML String Translation" (we use 1.5.0, August 27th 2012 on WordPress 3.4.1) - this is for translating things like admin texts, widgets, plugin strings and theme strings.
- Go to [Admin Panel > WPML > Languages] and add second language. At first run some wizard to setup language will appear. Also, setup everything else to your liking. There aren't many options worth mentioning here. I didn't change much here. I just disabled default language switcher and disabled flags in "What to include in the language switcher". I also picked URL format.
- Go to [Admin Panel > WPML > Theme and plugins localization]. Here you can either choose to "translate using .MO file" or "translate by WPML". The good practice would be to download POEdit at this stage, go to /languages/ folder in theme folder and load daisho.pot. Then setup all POEdit settings to your liking (such as plural forms) and translate everything or a substantial part of strings. Then generate .MO file for your language. Please keep intact copy of daisho.pot in /languages/ folder and create .PO files out of it for your language. Then generate .MO file using your .PO file (and not daisho.pot). PO file is basically the same as POT file. It contains not translated theme strings. Once you have your strings ready in .MO file you can check any of those options - either "translate using .MO file" or "translate by WPML". I chose "translate by WPML" - this will store translation options in WPML database tables which may not be very convenient in some situations but it gives you more control. By using this you actually load your MO file and in addition you have ability to overwrite some translations
- Go to [Admin Panel > WPML >String Translation] and pay attention to "Info box", "Welcome Text" etc. Those contain IDs of pages that can be picked under [Daisho > General]. Such options have been already mentioned in this document. Other than this - there shouldn't be any unordinary things there.
- From now you can translate Menus, Posts, Pages (according to WPML instructions). There shouldn't be many problems with that.
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