How to Translate a WordPress Theme

There are many sources where you could find instructions for how to translate WordPress theme. Of course the first place where you should start is the WordPress CodexTranslating WordPress. There you could find all the information you need to translate your WordPress theme.

In one of the client’s project in which I’ve been working on I had to prepare and generate *.po and *.pot files for one of his themes and the theme framework that we are working on. I followed several steps and I’ll share with you yet another ‘tutorial’ of how to

Generate POT file for WordPress Theme

Start Poedit
– You could download Poedit from here or to install it from the Terminal if you are using *nix OS:

sudo apt-get install poedit

Click File -> New Catalog

Enter a Project name (probably your theme’s file name).

Click the Sources Paths tab at the top.

Click the New Item icon (second one, looks like a little square).
Enter the path to the directory containing your theme file (“.” tells Poedit to scan the directory that you will save the file to), press enter.
Example: /home/metodiew/projects/path-to-wp-theme/

Click the Keywords tab at the top

Click the New Item icon
Enter __ (that’s underscore underscore), press Enter

Click the New Item icon
Enter _e (that’s underscore e), press Enter

Click Okay

Choose a name for your .po file (probably your theme’s base filename)

The Update Summary window should display, with a list of strings that were found to translate, based on the keywords supplied above (__ and _e). Click Okay.

Best Practice

If you want to follow the best practice, create a folder called languages and put the translation files in that folder. Save the *.po file, and Exit the program.
Also you could make the .po file available for download (or optionally include it in the theme archive). In that way you will provide option to other people to translate your theme in other languages.

Translators will use this file to construct a *.mo file, which will be used by the load_theme_textdomain() function.


function your_theme_after_theme_setup() {

    // ******************* Localizations ****************** //
    load_theme_textdomain( 'your_theme_textdomain', get_template_directory() . '/languages/' );

    // here goes the rest of your code

add_action( 'after_setup_theme', 'your_theme_after_theme_setup' );

P.S. most of those instructions are taken from the Codex and you also could find many similar tutorials from many Internet resources. I just wanted to have this one in my blog, so I’ll could easily find and follow when I need to prepare translation for another themes.

Stanko Metodiev is a WordPress veteran and the CTO of DevriX. For the past 12 years Stanko has been developing complex SaaS platforms, multisite solutions, migrating various systems to WordPress, managing a team of developers and leading a few key international projects in the company. In the past years, Stanko is the lead organizer of the WordPress Sofia User Group (WPBGUG) and has been a part of the organization of WordCamp Sofia and WordCamp Bulgaria. In his portfolio, you can find free themes and plugins on, and badges of his membership in the WordPress support, polyglots, theme reviews teams. Stanko is a fan of Real Madrid and often watches football games in shisha bars with friends and with his family at home. Also an avid fan of Counter-Strike and an active member of the remote work culture worldwide.

Tagged with: , , , ,
Posted in Tips and Tricks, WordPress

Leave a Reply

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.

A proud DevriX team member

WordPress Development agency building complete solutions for successful businesses.

WordPress Core Contributions
  • [49216] Bundled Themes: Import Twenty Twenty-One, the new default theme for ...
  • [43345] I18N: Remove unused MediaElement.js strings. Props metodiew. See ...
  • [42160] About: Fix grammar typo with pluralization. Props metodiew, ...
  • [42159] About: Fix grammar typo with pluralization. Props metodiew, ...
  • [41339] Widgets: Use `word-wrap: break-word` for available widget ...

View all 15 tickets on Trac.

Recent Posts
Recent Comments