Setting Up and Registering Localized Theme Text Domains and Translations in Multi-Language Site Networks

Understanding Text Domains in WordPress

A text domain is a unique identifier used by WordPress to distinguish the translation files for a specific theme or plugin. When you use translation functions like __('Text to translate', 'text-domain'), WordPress looks for a corresponding translation file (e.g., text-domain-fr_FR.mo) within the wp-content/languages/themes/ or wp-content/languages/plugins/ directories. For themes, this text domain is typically defined in the theme’s style.css header and is crucial for enabling internationalization (i18n) and localization (l10n).

Defining the Text Domain in Your Theme’s `style.css`

The first step in making your theme translatable is to declare its text domain. This is done in the theme’s main style.css file. The text domain should be unique to your theme and follow WordPress coding standards (lowercase, hyphens instead of spaces). It’s also good practice to use a slug that reflects your theme’s name.

Here’s an example of the required header in style.css:

/*
Theme Name: My Awesome Theme
Theme URI: https://example.com/my-awesome-theme/
Author: Your Name
Author URI: https://example.com/
Description: A brief description of your theme.
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-awesome-theme
Domain Path: /languages
Tags: custom-background, custom-menu, featured-images, theme-options
*/

The Text Domain line specifies the unique identifier. The Domain Path line tells WordPress where to find the translation files relative to the theme’s root directory. In this case, translations will be looked for in the /languages folder within your theme.

Internationalizing Strings in Your Theme’s PHP Files

Once the text domain is defined, you need to wrap all user-facing strings in your theme’s PHP files with WordPress’s internationalization functions. The most common ones are __() for outputting translated strings and _e() for echoing translated strings directly.

Consider a template file (e.g., single.php) with the following code:

<?php
/**
 * The template for displaying single posts.
 *
 * @package My_Awesome_Theme
 */

get_header(); ?>

<div id="primary" class="content-area">
    <main id="main" class="site-main" role="main">

    <?php while ( have_posts() ) : the_post(); ?>

        <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
            <header class="entry-header">
                <h1 class="entry-title"><?php the_title(); ?></h1>
                <div class="entry-meta">
                    <span class="posted-on"><?php echo esc_html__( 'Posted on', 'my-awesome-theme' ); ?> <time class="entry-date published updated" datetime="<?php echo esc_attr( get_the_date( 'c' ) ); ?>"><?php echo esc_html( get_the_date() ); ?></time></span>
                    <span class="byline"><?php echo esc_html__( 'by', 'my-awesome-theme' ); ?> <span class="author vcard"><?php the_author_meta( 'display_name' ); ?></span></span>
                </div><!-- .entry-meta -->
            </header><!-- .entry-header -->

            <div class="entry-content">
                <?php
                    the_content( sprintf(
                        /* translators: %s: name of current post */
                        wp_kses( __( 'Continue reading %s →', 'my-awesome-theme' ), array( 'span' => array( 'class' => array() ) ) ),
                        the_title( '<span class="screen-reader-text">', '</span>', false )
                    ) );

                    wp_link_pages( array(
                        'before' => '<div class="page-links">' . esc_html__( 'Pages:', 'my-awesome-theme' ),
                        'after'  => '</div>',
                    ) );
                ?>
            </div><!-- .entry-content -->

            <footer class="entry-footer">
                <?php // Some footer content here, also translatable ?>
                <?php echo esc_html__( 'Category:', 'my-awesome-theme' ); ?> <?php the_category( ', ' ); ?>
            </footer><!-- .entry-footer -->
        </article><!-- #post-## -->

    <?php endwhile; // End of the loop. ?>

    </main><!-- #main -->
</div><!-- #primary -->

<?php get_sidebar(); ?>
<?php get_footer(); ?>

In this example, strings like 'Posted on', 'by', 'Continue reading %s →', 'Pages:', and 'Category:' are wrapped with esc_html__() or wp_kses() and the text domain 'my-awesome-theme'. This ensures that these strings can be found by translation tools.

Generating the `.pot` File

A Portable Object Template (.pot) file is a master file containing all the translatable strings from your theme. It serves as the basis for creating language-specific translation files (.po and .mo). You can generate this file manually or, more practically, using a tool.

Using WP-CLI for `.pot` Generation

WP-CLI is the command-line interface for WordPress. It provides a convenient way to manage your WordPress installation, including generating translation files. Ensure you have WP-CLI installed and navigate to your WordPress root directory.

To generate a .pot file for your theme, use the following command:

wp i18n make-pot . languages/my-awesome-theme.pot --headers='{"Language-Team":"My Awesome Theme Team <[email protected]>", "X-Generator":"WP-CLI/<version> <url>"}'

Explanation:

• wp i18n make-pot: The WP-CLI command to create a POT file.
• .: Specifies the current directory (your theme’s root) as the source.
• languages/my-awesome-theme.pot: The destination path and filename for the generated POT file. This should match your Domain Path in style.css.
• --headers='...': Allows you to add custom headers to the POT file, such as the Language Team and the generator information. Replace <version> and <url> with actual values if desired, or let WP-CLI populate them.

After running this command, a my-awesome-theme.pot file will be created in the languages directory of your theme. This file contains all the strings you’ve wrapped with internationalization functions.

Creating Language (`.po` and `.mo`) Files

The .pot file is a template. To create actual translations, you’ll need to convert it into a .po (Portable Object) file for each language. Translators edit the .po file. Then, a compiled binary .mo (Machine Object) file is generated from the .po file, which WordPress uses for translations.

Using Poedit for Translation Files

Poedit is a popular, free, cross-platform gettext translation editor. It simplifies the process of creating and editing .po files.

• Download and install Poedit from poedit.net.
• Open Poedit.
• Go to File > New from POT/PO file….
• Select your generated my-awesome-theme.pot file.
• Poedit will prompt you to choose the language for this translation. Select the desired language (e.g., French – fr_FR).
• Poedit will then create a new .po file (e.g., fr_FR.po) and open it.
• Go through each string and provide its translation in the corresponding field.
• Once you’ve finished translating, save the file. Poedit will automatically generate the fr_FR.mo file alongside the fr_FR.po file.

Place these generated fr_FR.po and fr_FR.mo files into the wp-content/themes/my-awesome-theme/languages/ directory (or wherever your Domain Path points).

Handling Translations in WordPress Multisite

In a WordPress Multisite installation, themes and plugins can be activated on a per-site basis or network-wide. The location where translation files are loaded can differ, especially with the introduction of the `languages` directory in WordPress 4.6.

Default Translation Loading Path

WordPress 4.6 and later introduced a central `wp-content/languages/` directory for themes and plugins. This is the preferred location for translation files.

• Theme Translations: wp-content/languages/themes/my-awesome-theme-fr_FR.mo
• Plugin Translations: wp-content/languages/plugins/my-plugin-fr_FR.mo

If a translation file exists in this central directory, WordPress will use it, overriding any translations found within the theme or plugin’s own `languages` folder (as defined by `Domain Path`). This is beneficial for network administrators as they can manage all translations centrally.

Theme-Specific Translation Loading

Your theme’s Domain Path (e.g., `/languages`) still plays a role. If a translation file is not found in the central wp-content/languages/ directory, WordPress will then look in the theme’s own `languages` folder:

• wp-content/themes/my-awesome-theme/languages/fr_FR.mo

For themes, the text domain is part of the filename when using the central directory. For example, my-awesome-theme-fr_FR.mo. When using the theme’s own `languages` folder, the filename is typically just fr_FR.mo (assuming the text domain matches the theme’s slug).

Network Activation vs. Site Activation

When a theme is network-activated, its translations in the central wp-content/languages/themes/ directory will be available to all sites on the network. If the theme is only activated on specific sites, the same translation files will be used for those sites.

The key takeaway for Multisite is that the central wp-content/languages/ directory is the primary location. Network administrators can upload translation files here to make them available across the entire network.

Advanced Diagnostics: Troubleshooting Translation Issues

If your theme’s strings are not translating correctly, here’s a systematic approach to diagnose the problem:

1. Verify Text Domain Consistency

Double-check that the Text Domain in your style.css header exactly matches the text domain used in your internationalization functions (e.g., 'my-awesome-theme'). A typo here is a common mistake.

2. Check `Domain Path` Configuration

Ensure the Domain Path in style.css correctly points to the directory containing your translation files relative to the theme’s root. If you’re using the central wp-content/languages/themes/ directory, this path is less critical for loading but still important for .pot generation.

3. Confirm File Naming Conventions

Translation files must follow specific naming conventions:

• Central Languages Directory: [text-domain]-[locale].mo (e.g., my-awesome-theme-fr_FR.mo)
• Theme’s Domain Path Directory: [locale].mo (e.g., fr_FR.mo)

The locale (e.g., fr_FR) must match the language code set in WordPress’s General Settings (Settings > General > Site Language).

4. Inspect Translation File Contents

Open the .po file in a text editor or Poedit. Verify that the strings you expect to be translated are present and correctly marked as “fuzzy” or “translated.” Ensure the header information in the .po file is accurate.

5. Check WordPress Site Language Setting

Go to Settings > General in your WordPress admin. The Site Language dropdown must be set to the language for which you have translation files (e.g., French). If this setting doesn’t match your translation file’s locale, translations won’t load.

6. Clear Caches

Caching plugins, server-level caches (like Varnish or Nginx FastCGI cache), and even browser caches can prevent updated translations from appearing. Clear all relevant caches after uploading or modifying translation files.

7. Use `gettext` Debugging (Advanced)

For deeper debugging, you can temporarily enable `gettext` debugging. Add the following to your wp-config.php file:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'ENABLE_GETTEXT_GRUMBLE', true );

With ENABLE_GETTEXT_GRUMBLE defined as true, WordPress will output warnings to the wp-content/debug.log file whenever it cannot find a translation for a string. This can pinpoint exactly which strings are failing and why.

8. Multisite Specific: Network Admin vs. Site Admin

Ensure you are checking translations on a site where the theme is actually activated. If you are a network admin, verify that the theme is activated for the specific site you are testing. Also, confirm that the translation files are placed in the correct location for network-wide availability (wp-content/languages/themes/) or within the theme’s directory if that’s your chosen method.