Developer Guides

Finding Missing Translations in Your WordPress Plugin or Theme

If parts of your plugin or theme appear untranslated after using PTC, use this guide to check whether the string is part of your project and whether WordPress is loading the correct file.

Check if the String Is Available in PTC

From the PTC dashboard, go to the Translations tab and search for the original string. If you don’t see it, PTC didn’t receive it. This usually means one of the following:

  • The string is missing from your POT file

If your POT doesn’t include all translatable strings, recreate it using WP-CLI. Then, follow the steps in our WordPress theme and plugin internationalization guide from the start.

  • The text isn’t wrapped in a GetText function

Make sure all translatable text is wrapped in __() or _e() and uses the correct text domain.

Example:

__('Hello, world!', 'your-plugin');

For more details, see Step 2 of our WordPress theme and plugin translation guide.

  • JavaScript strings weren’t marked as translatable

If your plugin includes translatable text in JavaScript:

  1. Go to PTC → Settings and click on Monitored Files. Edit the relevant resource file, and enable “Is this a WordPress project with localizable JavaScript?”
Telling PTC that your product includes translatable text in Javascript

This tells PTC to scan JavaScript files for translatable strings. It will regenerate translations and create a new merge request with updated files.

  1. Make sure WordPress knows where to load the .json translation files created by PTC.

If the .json files are placed inside your plugin or theme’s /languages/ directory, call wp_set_script_translations() with the correct path.

For plugins:

wp_set_script_translations( 'script-handle', 'text-domain', plugin_dir_path( __FILE__ ) . 'languages' );

For themes:

wp_set_script_translations( 'script-handle', 'text-domain', get_template_directory() . '/languages' );

This explicitly tells WordPress to load .json files from your plugin or theme folder.

Confirm WordPress Is Loading Your Translation Files

If the translated string appears in PTC but still doesn’t show in your plugin, WordPress may not be loading the correct translation file. Check the following:

  • Text domain is loaded correctly

If you’re using embedded plugins or multiple domains, make sure each one is loaded using load_plugin_textdomain() or load_theme_textdomain().

  • Translations from PTC aren’t being overridden

By default, WordPress prioritizes translation files in /wp-content/languages/. If your plugin or theme has translations created by the WordPress community, they can override your bundled .mo files.

To make sure WordPress loads your .mo files instead, apply the load_textdomain_mofile filter.

Example usage for plugins

Add the filter function to your plugin’s main PHP file (for example, my-plugin.php):

function my_plugin_load_embedded_translation_file( $mofile, $domain ) {
  // Replace 'my-domain' with your actual plugin's text domain
	if ( 'my-domain' === $domain && false !== strpos( $mofile, WP_LANG_DIR . '/plugins/' ) ) {
		$locale = apply_filters( 'plugin_locale', determine_locale(), $domain );
		$local_mofile = WP_PLUGIN_DIR . '/' . dirname( plugin_basename( __FILE__ ) ) . '/languages/' . $domain . '-' . $locale . '.mo';
		
		if ( file_exists( $local_mofile ) ) {
			return $local_mofile; // Use bundled translation if available
		}		
	}
	return $mofile;
}
add_filter( 'load_textdomain_mofile', 'my_plugin_load_embedded_translation_file', 10, 2 );

Example usage for themes

Add the filter function in your theme’s functions.php file:

function my_theme_load_embedded_translation_file( $mofile, $domain ) {
    // Replace 'my-domain' with your actual theme's text domain
    if ( 'my-domain' === $domain && false !== strpos( $mofile, WP_LANG_DIR . '/themes/' ) ) {
        $locale = apply_filters( 'theme_locale', determine_locale(), $domain );
        $local_mofile = get_template_directory() . '/languages/' . $locale . '.mo';
        
        if ( file_exists( $local_mofile ) ) {
            return $local_mofile; // Use bundled translation if available
        }
    }
    return $mofile;
}
add_filter( 'load_textdomain_mofile', 'my_theme_load_embedded_translation_file', 10, 2 );

Make Sure MO File Naming Matches WordPress Expectations

WordPress expects different naming conventions for .mo files depending on where you store them.

  • If your translation files are inside your theme folder, use:

{locale}.mo
Example: de_DE.mo (paired with de_DE.po)

  • If you placed the files in the global WordPress language directory (wp-content/languages/themes/), use:

{text-domain}-{locale}.mo
Example: my-theme-de_DE.mo (paired with my-theme-de_DE.po)

Developer Guides

Start typing and press enter to search

Scroll to Top