In the original release of Building Web Apps with WordPress, our chapter on localization included a section on localizing non-string assets. At the time, it seemed appropriate to include this information in case you needed to swap out images, text files, or html templates based on the chosen language. However, in practice, we almost never need to do this on the apps we’re building nowadays. Images rarely include text or other material to be translated. Instead of a folder full of .html files, templates are more often full on .php files or reference strings declared in other php files. Modern WordPress programming, even on the design side, expects a multidisciplined developer capable of editing .php files full of localized strings.

Further, our use of load_textdomain() over load_plugin_textdomain() and load_theme_textdomain() confused other plugins and tools that expect all properly localized plugins and themes to use one of those variants. The custom code we came up with to load the text domain with support for an assets folder turn out to be too clever.

We’ve decided to remove the section on localizing non-string assets from the second revision of the book. While localizing non-string assets hasn’t become as common a requirement as we once thought, the code and information below might be useful to developers who need to load the text domain in a similar way.

If you’ve read the localization chapter of Building Web Apps with WordPress, you will have everything you need to make sure any string used by your plugin, theme, or app is properly translated. However, you will sometimes have non-string assets that still need to be swapped out depending on the locale being used.

For example, you might have images with words in them that should be swapped for alternative images with those words translated. Maybe your localized app uses different colors for different countries; you can swap CSS files based on the detected locale.

In the past, we’ve used .html email templates in our plugins that need to be translated. We could wrap the entire email in one big __() function, or we could create a directory of templates for each language. The latter option might mean more work for your translators because they’ll have to generate .html templates along with the .mo files, but it will give developers using your code a bit more flexibility.

Below we’ll write some code to load images and email templates for our plugin based on the local. Assume we have folders like this:

  • schoolpress/images/ (default images)
  • schoolpress/emails/ (default email templates)
  • schoolpress/languages/es_ES/
  • schoolpress/languages/es_ES/images/ (Spanish-version images)
  • schoolpress/languages/es_ES/emails/ (Spanish-version email templates)

We’ll make sure that the functions that load these assets have hooks that will allow us to override which directory is used to get them.

In the following code, we assume that the constant SCHOOLPRESS_URL points to the relative URL for the SchoolPress plugin folder, for example, /wp-content/plugins/schoolpress/:

Now in our includes/localization.php folder, we can put some code in place that will filter schoolpress_images_url if a non-default locale is used:

You could do the same thing for loading emails. In the following code, we assume the constant SCHOOLPRESS_PATH points to the server pathname for the SchoolPress plugin, for example, /var/vhosts/schoolpress.com/httpdocs/wp-content/plugins/schoolpress/:

Let us know if you’ve found this tutorial useful or if you are doing anything similar to localize non-string assets in your WordPress projects.

Article by