How to Build WordPress Template Hierarchy rules in Multi-Language Site Networks

Understanding WordPress Template Hierarchy for Multilingual Sites

Building a multilingual WordPress site, especially within a multisite network, introduces complexities in how WordPress resolves which template file to use for displaying content. The standard WordPress template hierarchy dictates the order in which WordPress looks for template files (e.g., index.php, archive.php, single.php, page.php). When dealing with multiple languages, we need to ensure that the correct language-specific templates are prioritized. This involves understanding how WordPress handles conditional tags and how we can leverage them, often in conjunction with a plugin like WPML or Polylang, to influence template selection.

In a multisite setup, each subsite can potentially have its own language or set of languages. This means our template hierarchy rules might need to be applied on a per-site basis, or in a way that respects the global network settings if a consistent multilingual structure is desired across all subsites. The core challenge is to override or extend the default hierarchy to serve language-specific templates when a particular language is active.

Leveraging `template_include` Filter for Custom Template Logic

The most robust way to inject custom template logic into WordPress is by using the template_include filter. This filter allows us to intercept the path to the template file that WordPress is about to load and, if necessary, return a different path to a custom template file. This is particularly powerful for multilingual sites because we can check the current language and serve a language-specific template.

For this to work effectively in a multisite environment, we need to consider the context of the current site. WordPress provides the get_current_blog_id() function to identify the active subsite.

Example: Prioritizing Language-Specific Single Post Templates

Let’s assume we have a theme with English and French versions of templates. For single posts, we might want to use single-en.php for English content and single-fr.php for French content. If these specific files don’t exist, we’d fall back to the standard single.php.

This logic would typically be placed in your theme’s functions.php file or a custom plugin.

Theme’s Template Files Structure (Example)

Your theme directory might look something like this:

your-theme/
├── single.php (Fallback)
├── single-en.php (English specific)
├── single-fr.php (French specific)
├── page.php (Fallback)
├── page-en.php (English specific)
├── page-fr.php (French specific)
└── functions.php

Implementing the `template_include` Filter

Here’s the PHP code to add to your theme’s functions.php:

<?php
/**
 * Filter the template include path to prioritize language-specific templates.
 *
 * @param string $template The path to the template file.
 * @return string The path to the template file to be used.
 */
function my_multilingual_template_include( $template ) {
    // Ensure we are on the frontend and not in an admin context.
    if ( is_admin() ) {
        return $template;
    }

    // Get the current language code. This assumes a plugin like WPML or Polylang is active
    // and provides a reliable way to get the current language.
    // For WPML: ICL_LANGUAGE_CODE constant or apply_filters('wpml_current_language', NULL)
    // For Polylang: pll_current_language()
    $current_language = null;

    if ( defined( 'ICL_LANGUAGE_CODE' ) ) {
        $current_language = ICL_LANGUAGE_CODE;
    } elseif ( function_exists( 'pll_current_language' ) ) {
        $current_language = pll_current_language();
    }

    // If no language is detected or it's the default language, use the original template.
    // You might want to adjust this logic if your default language is not 'en'.
    if ( ! $current_language || $current_language === 'en' ) {
        return $template;
    }

    // Determine the template type based on WordPress conditional tags.
    $new_template = $template;

    if ( is_single() ) {
        $custom_template = get_template_directory() . '/single-' . esc_attr( $current_language ) . '.php';
        if ( file_exists( $custom_template ) ) {
            $new_template = $custom_template;
        }
    } elseif ( is_page() ) {
        $custom_template = get_template_directory() . '/page-' . esc_attr( $current_language ) . '.php';
        if ( file_exists( $custom_template ) ) {
            $new_template = $custom_template;
        }
    } elseif ( is_archive() ) {
        // For archives, you might want to check for category-specific or tag-specific templates first.
        // Example: archive-post-fr.php, category-news-fr.php, tag-events-fr.php
        // This example simplifies to a general archive-fr.php
        $custom_template = get_template_directory() . '/archive-' . esc_attr( $current_language ) . '.php';
        if ( file_exists( $custom_template ) ) {
            $new_template = $custom_template;
        }
    }
    // Add more conditions for other template types (e.g., home, front page, search results, etc.)

    // If a custom template was found and assigned, return it. Otherwise, return the original.
    return $new_template;
}
add_filter( 'template_include', 'my_multilingual_template_include', 99 ); // Use a high priority to ensure it runs late.
?>

Explanation:

The filter hook template_include is attached. A priority of 99 is used to ensure our logic runs after most other template-related filters.
We first check if we are in the admin area to avoid interfering with backend operations.
We then attempt to detect the current language using constants or functions provided by popular multilingual plugins (WPML and Polylang). You’ll need to adapt this part based on the specific plugin you are using or your custom language detection method.
If a language is detected and it’s not the default language (here assumed to be ‘en’), we proceed.
We use WordPress conditional tags like is_single() and is_page() to determine the context of the content being displayed.
For each context, we construct the path to the potential language-specific template (e.g., single-fr.php).
We check if this custom template file actually exists within the theme’s directory using get_template_directory() and file_exists().
If the custom template exists, we update the $new_template variable with its path.
Finally, the filter returns either the path to the custom language-specific template or the original template path if no custom one was found or applicable.

Multisite Considerations: Per-Site Template Logic

In a multisite network, each subsite can have its own language settings and content. The previous example works well if all subsites share the same theme and the language detection is global. However, if you have different themes per subsite or need more granular control, you’ll need to incorporate the current blog ID into your logic.

Accessing Current Blog ID

The function get_current_blog_id() returns the ID of the currently active subsite. You can use this to conditionally apply template logic or to load different template files based on the subsite’s configuration.

Example: Site-Specific Language Templates

Let’s say Site ID 2 is exclusively for French content, and Site ID 3 is for Spanish content. We can modify the template_include filter to account for this.

<?php
/**
 * Filter the template include path for multilingual and multisite specific templates.
 *
 * @param string $template The path to the template file.
 * @return string The path to the template file to be used.
 */
function my_multilingual_multisite_template_include( $template ) {
    if ( is_admin() ) {
        return $template;
    }

    $current_blog_id = get_current_blog_id();
    $current_language = null;

    // --- Language Detection Logic (as before) ---
    if ( defined( 'ICL_LANGUAGE_CODE' ) ) {
        $current_language = ICL_LANGUAGE_CODE;
    } elseif ( function_exists( 'pll_current_language' ) ) {
        $current_language = pll_current_language();
    }
    // --- End Language Detection ---

    // --- Site-Specific Language Overrides ---
    // Example: Site ID 2 is French, Site ID 3 is Spanish
    if ( 2 === $current_blog_id ) {
        $current_language = 'fr'; // Force French for this site
    } elseif ( 3 === $current_blog_id ) {
        $current_language = 'es'; // Force Spanish for this site
    }
    // --- End Site-Specific Overrides ---

    // If no language is determined or it's the default, return original.
    if ( ! $current_language || $current_language === 'en' ) {
        return $template;
    }

    $new_template = $template;
    $theme_dir = get_template_directory(); // Use get_stylesheet_directory() if using child themes extensively

    if ( is_single() ) {
        // Prioritize: single-[lang]-[blog_id].php > single-[lang].php > single.php
        $site_lang_template = $theme_dir . '/single-' . esc_attr( $current_language ) . '-' . $current_blog_id . '.php';
        $lang_template = $theme_dir . '/single-' . esc_attr( $current_language ) . '.php';

        if ( file_exists( $site_lang_template ) ) {
            $new_template = $site_lang_template;
        } elseif ( file_exists( $lang_template ) ) {
            $new_template = $lang_template;
        }
    } elseif ( is_page() ) {
        // Prioritize: page-[lang]-[blog_id].php > page-[lang].php > page.php
        $site_lang_template = $theme_dir . '/page-' . esc_attr( $current_language ) . '-' . $current_blog_id . '.php';
        $lang_template = $theme_dir . '/page-' . esc_attr( $current_language ) . '.php';

        if ( file_exists( $site_lang_template ) ) {
            $new_template = $site_lang_template;
        } elseif ( file_exists( $lang_template ) ) {
            $new_template = $lang_template;
        }
    }
    // Add more conditions for archives, custom post types, etc.

    return $new_template;
}
add_filter( 'template_include', 'my_multilingual_multisite_template_include', 99 );
?>

Key additions and considerations:

We explicitly check $current_blog_id to potentially override the detected language. This is useful if a subsite is dedicated to a specific language, regardless of the user’s browser settings or the default language set in the multilingual plugin.
The template file naming convention is extended to include the blog ID: single-fr-2.php. This allows for highly specific templates for a particular language on a particular subsite.
A prioritization order is introduced: single-[lang]-[blog_id].php > single-[lang].php > single.php. This provides a fallback mechanism, ensuring that content is always displayed, even if the most specific template isn’t available.
Using get_template_directory() assumes you are modifying the parent theme. If you are using a child theme, you should use get_stylesheet_directory() to ensure your custom templates are found within the child theme’s directory.

Advanced Template Hierarchy: Custom Post Types and Taxonomies

The template hierarchy extends to custom post types (CPTs) and custom taxonomies. For example, if you have a CPT called ‘Events’ and a taxonomy called ‘Event Categories’, WordPress will look for templates like:

single-event.php (for single event posts)
archive-event.php (for event archives)
taxonomy-event_category.php (for event category archives)
term.php (fallback for taxonomy archives)

To make these multilingual, you can apply the same principles as with standard posts and pages.

Example: Multilingual Custom Post Type Templates

<?php
/**
 * Filter the template include path for multilingual CPTs and taxonomies.
 *
 * @param string $template The path to the template file.
 * @return string The path to the template file to be used.
 */
function my_multilingual_cpt_template_include( $template ) {
    if ( is_admin() ) {
        return $template;
    }

    $current_language = null;
    if ( defined( 'ICL_LANGUAGE_CODE' ) ) {
        $current_language = ICL_LANGUAGE_CODE;
    } elseif ( function_exists( 'pll_current_language' ) ) {
        $current_language = pll_current_language();
    }

    if ( ! $current_language || $current_language === 'en' ) {
        return $template;
    }

    $new_template = $template;
    $theme_dir = get_template_directory();

    // --- Custom Post Type: Events ---
    if ( 'event' === get_post_type() ) {
        $custom_template = $theme_dir . '/single-event-' . esc_attr( $current_language ) . '.php';
        if ( file_exists( $custom_template ) ) {
            $new_template = $custom_template;
        }
    }

    // --- Custom Taxonomy: Event Categories ---
    if ( is_tax( 'event_category' ) ) {
        // Prioritize: taxonomy-[taxonomy]-[slug]-[lang].php > taxonomy-[taxonomy]-[lang].php > taxonomy-[lang].php > taxonomy-[taxonomy].php
        $term = get_queried_object();
        $term_slug = $term->slug;

        $site_lang_term_template = $theme_dir . '/taxonomy-event_category-' . esc_attr( $term_slug ) . '-' . esc_attr( $current_language ) . '.php';
        $lang_term_template = $theme_dir . '/taxonomy-event_category-' . esc_attr( $current_language ) . '.php';
        $general_lang_term_template = $theme_dir . '/taxonomy-' . esc_attr( $current_language ) . '.php'; // Fallback for any taxonomy

        if ( file_exists( $site_lang_term_template ) ) {
            $new_template = $site_lang_term_template;
        } elseif ( file_exists( $lang_term_template ) ) {
            $new_template = $lang_term_template;
        } elseif ( file_exists( $general_lang_term_template ) ) {
            $new_template = $general_lang_term_template;
        }
    }

    // Add more CPTs and taxonomies as needed...

    return $new_template;
}
add_filter( 'template_include', 'my_multilingual_cpt_template_include', 99 );
?>

This example demonstrates how to create language-specific templates for a custom post type (‘event’) and a custom taxonomy (‘event_category’). The naming convention follows the pattern [base_template]-[language_code].php. For taxonomies, you can even get more granular by including the term slug in the filename (e.g., taxonomy-event_category-concert-fr.php).

Best Practices and Further Considerations

Child Themes: Always implement these customizations in a child theme. This prevents your modifications from being overwritten when the parent theme is updated. Use get_stylesheet_directory() instead of get_template_directory() in your child theme’s functions.php.
Multilingual Plugin Integration: Ensure your language detection logic is compatible with your chosen multilingual plugin (WPML, Polylang, TranslatePress, etc.). The provided examples use common methods, but you might need to consult your plugin’s documentation for the most accurate way to retrieve the current language.
Performance: While the template_include filter is powerful, excessive file checks within it can impact performance. Cache template paths where possible or ensure your file system is efficient. For very complex scenarios, consider pre-calculating template paths during plugin/theme activation.
Theme Structure: Organize your language-specific templates logically. You might create subdirectories like /languages/fr/ or /templates/fr/, but remember to adjust your file paths in the filter accordingly.
Fallback Strategy: Always have a robust fallback strategy. Ensure that if a language-specific template is missing, WordPress gracefully falls back to a more general template (e.g., single.php) rather than throwing an error.
Testing: Thoroughly test your template hierarchy rules across all relevant languages, post types, taxonomies, and on different subsites within your multisite network. Use browser developer tools to inspect the loaded template file name if unsure.

By understanding and strategically applying the template_include filter, you can build sophisticated and maintainable multilingual template hierarchies for your WordPress multisite installations, ensuring that content is displayed with the correct language and context.