Using Polylang with Customizr WordPress theme

UPDATE 12 April 2015 Since Customizr 3.3.17, Customizr-Pro 1.1.2, Featured Pages Unlimited 2.0.9 and Featured Pages Customizr 1.4.1 the Polylang bridge code has been embedded in the core (along with compatibility code for qtranslateX). You better remove it from your child-theme functions.php then, to avoid any conflicts or malfunctions.

Code updated 26 March 2015: Works with Customizr > 3.3.13, Customizr-Pro >= 1.0.17, Featured Pages Unlimited

This guide shows you how to set up a multilingual site with the Polylang plugin and the Customizr theme. It contains some “bridge” code, which makes them work together. Bonus: The code included below also works with Featured Pages Unlimited and Polylang, using any other theme.

Bridge-code updated 22 May 2014: Corrected case where running Customizr and Featured Pages Unlimited, where slider choice was not being picked up; removed stray line-end; removed unnecessary double-checking for FPU in translation panel.

First, a word about language plugins:

 

Customizr and free language plugins

 

qTranslate and mqTranslate

Customizr fully supports qTranslate for multilingual sites. qTranslate is a very popular free plugin that is tightly integrated with the WordPress admin screens. To use qTranslate with Customizr, you use shortcodes to enter the text on the featured pages, sliders, buttons, etc. For each page, qTranslate keeps all the languages together in the page and, when requested, presents the browser with a subset of the text in the right language.

Because of the tight integration with WordPress, qTranslate is very sensitive to WordPress changes. In order to make sure that it doesn’t break with the latest WordPress update, some parts of the plugin disable themselves every time there is a WordPress update. Your site still works fine, but it’s harder to manage your pages until it is updated—which can sometimes take a while. For this reason, some people are switching to the mqTranslate plugin. This is a fork of qTranslate. mqTranslate is not yet supported by Customizr, but in principle it should be possible to add support in the same way.

If you uninstall qTranslate or mqTranslate, they leave your site full of shortcodes to clean up and they leave your pages with two or more languages in each page.

 

Polylang

Polylang is another popular WordPress plugin for multilingual sites. Polylang takes a different approach to qTranslate and mqTranslate. Each language has its own page and, when requested, Polylang presents the browser with the correct page in the right language. In order for Polylang to do this, you define a language for each page and tell Polylang how to link them together. This is a similar approach to the one taken by the paid-for plugin WPML.

One advantage with Polylang is that your pages—and all the text inside the pages—are left entirely intact if you uninstall. Nothing to clean up.

Polylang didn’t work well with Customizr—until now—because it didn’t support Customizr’s front page and sliders. Extra work is needed to make them show correctly. This snippet puts the Customizr text in featured pages and buttons, together with your slider names, into Polylang’s Strings translation panel, so that you can translate the text and substitute the slider names.

Enough background; let’s get down to work.

 

Setting up WordPress + Customizr + Polylang

Don’t be put off by the number of steps to complete below. The steps are very comprehensive and lead you through the process. Depending on the size of your site and your skill level, it doesn’t take much time to have a fully-functional multilingual site with Customizr.

 

Set up WordPress and Customizr

First, read Setting up WordPress multilingual sites with Customizr, which explains the essentials of setting up WordPress for your languages. This will get you to a point where all the phrases like “Post navigation”, “Category archives”, etc. are automatically translated.

 

Create your content

Create the site’s content in your languages. If you currently have two (or more) sites in different languages, you can use WordPress’s export on each site and then use WordPress’s import to get them all into one site.

 

Install Polylang

Install and setup Polylang, using Polylang’s documentation. The documentation is good and covers all the options. The steps are as follows:

1. Add your languages to Polylang, using Dashboard > Settings > Languages > Languages (see Polylang’s help).
2. Edit the settings in the Settings tab (see Polylang’s help):
   • If this is the first time you’re using Polylang, it will ask you whether you want to automatically assign all the pages to the default language. Choose this option, as it will save you a lot of work in the next step.
   • Select The language is set from the directory name in pretty permalinks. This option has been fully tested and works well.
   • Change the other settings as you wish. You may choose to set the Activate languages and translations for media option, but this isn’t necessary for the Customizr-Polylang bridge code to work.
3. In Polylang’s settings, choose the String translations tab and translate your site’s title and tagline.
4. Next, you need to tell Polylang the language(s) of your other pages. The quickest way to do this is as follows:
   • On the All pages list, select the check box next to all the pages in your second language;
   • In the Bulk actions dropdown, select Edit and click Apply;
     
   • Change the language to your second language and click Update;
   • Repeat for all other languages (if any);
   • Edit every page in the non-default language and link it to equivalent page in the default language. Tip: Use the Ctrl (Windows) or cmd (OS X) key as you click, opening all the pages that you need to edit in separate browser tabs, then close them after you update each one—it helps you keep track. Remember to click Update on each page.
5. Repeat step 4 for all your posts (and for all your media if you have different images for each language).
6. In Posts > Categories, edit each category that isn’t in your default language, change its language, and link it to the equivalent category in the default language.
7. If you have chosen to show a static page on your front page in WordPress/Customizr (and thus have a blog page called “blog”, for example) then you will to need to create another blog page for each language. (If your front page displays your latest posts, you don’t need to do this.)
8. In Appearance > Menus, set up a menu for every language. Choose names to help you remember which is which. For example: “main-menu-en“, “main-menu-fr“, and so on. In the Manage locations tab, set each language menu to be the main menu for that language.
9. With Appearance > Widgets, set up a Polylang language-switcher widget (and customize your other widgets) in one of Customizr’s widget areas, as explained in Polylang’s documentation.

 

Set up the sliders

The Customizr-Polylang bridge code is written to give you full flexibility for your sliders, having different sets of slides for each language. This is helpful if your slides have cultural references or other language references in them.

So you need to set up a slider for each language:

1. For each language, upload the images to be used in each slider. If you use the same image in two different language’s slides, you need to upload them twice. Tip: Take the opportunity to change their filenames to be descriptive in the languages of your site. It will improve the chances of your images (and pages/posts) being ranked higher in search engines.
2. If you have selected the Activate languages and translations for media option in Polylang, you must set the language of each slide by editing each one. (If you haven’t selected that option, then you don’t need to do this.)
3. Create a new slider for each language following the Customizr instructions. If you have many sliders or many languages, try to name them in a way that you will remember later. For example, you could call your front page sliders “main-en-slider”, “main-fr-slider”, etc., and call your page sliders “page-name-en-slider”, “page-name-fr-slider”, etc.
4. For each slide, fill in the Title, Description, and Button text for each, as you wish, in the relevant language.

At this point, you have a basic Polylang setup. But your Customizr front page will not be showing in all your languages. This is where the Customizr-Polylang bridge code comes in.

 

Install the Customizr-Polylang bridge code

Note (12 April 2015): Since Customizr 3.3.17, Customizr-Pro 1.1.2, Featured Pages Unlimited 2.0.9 and Featured Pages Customizr 1.4.1 the Polylang bridge code has been embedded in the core (along with compatibility code for qtranslateX). You better remove it from your child-theme functions.php then, to avoid any conflicts or malfunctions.

Add this code to your child-theme’s functions.php:

 

// ====================================================================================================================
// Customizr-Polylang bridge: Makes the Customizr theme or the Featured Pages Unlimited
// plugin compatible with Polylang; Runs only if Polylang is active;
// ====================================================================================================================
 
// If Polylang is active, hook function on the admin pages
if ( function_exists( 'pll_register_string' ) ) add_action( 'admin_init', 'pll_tc_strings_setup' );
 
function pll_tc_strings_setup() {
 
    // Find out what code we're running for our featured pages.
    $running_fpu            = ( class_exists( 'TC_fpu' ) );
    $running_customizr      = ( ( wp_get_theme()->Template ) == 'customizr' );
    $running_customizr_pro  = ( ( wp_get_theme()->Template ) == 'customizr-pro' );
    $pll_tc_options         = array();
    $pll_tc_areas           = array();
    $pll_tc_archive_titles = array(
        'tag'     => 'Tag pages title', 
        'cat'     => 'Category pages titles',
        'author'  => 'Author pages titles',
        'search'  => 'Search results page titles'
    );
    $button_text_option_prefix = 'tc_featured_page_';

    if ( $running_customizr || $running_customizr_pro ) { // Running Customizr(-pro) alone
 
        // Get Customizr(-pro) options
        $pll_tc_options = TC_utils::$inst->tc_get_theme_options();
        
        if ( $running_customizr ){ // get array of featured pages / set Polylang's translation group
            $pll_tc_areas = TC_init::$instance->fp_ids;
            $fp_polylang_group = $polylang_group = 'Customizr';
        }
    }
    if ( $running_fpu && class_exists('TC_utils_fpu') ) { // Running Featured Pages Unlimited plugin (included in Customizr-pro) : Setup FPU-defined featured page strings

        // Get FPU options / get array of featured pages / set Polylang's translation group
        $option_name = $running_customizr_pro ? 'tc_pro_fpu' : 'tc_unlimited_featured_pages';
        $_pll_tc_options = array_merge(TC_utils_fpu::$instance -> default_options, get_option( $option_name ) );
        
        $pll_tc_options = array_merge($pll_tc_options, $_pll_tc_options);
        $_pll_tc_areas = TC_utils_fpu::$instance->tc_get_custom_fp_nb();
        $pll_tc_areas = array_unique( array_merge($pll_tc_areas, $_pll_tc_areas) );

        $fp_polylang_group = 'Featured Pages Unlimited';
        
        $button_text_option_prefix = 'tc_fp_';
    }
    if ( $running_customizr_pro )
        $fp_polylang_group = $polylang_group = 'Customizr-Pro';

    // Add featured pages button text to Polylang's string translation panel
    if ( isset( $pll_tc_options[ $button_text_option_prefix . 'button_text'] ) )
        pll_register_string( 'Featured pages button text', esc_attr($pll_tc_options[ $button_text_option_prefix . 'button_text']), $fp_polylang_group );
 
    // Add featured pages excerpt text to Polylang's string translation panel
    foreach ( $pll_tc_areas as $area )
        if ( isset( $pll_tc_options['tc_featured_text_'.$area] ) )
            pll_register_string( 'Featured text '.$area.'(200 char. max)', esc_attr($pll_tc_options['tc_featured_text_'.$area]), $fp_polylang_group );
    
 
    // Add front page slider name to Polylang's string translation panel
    if ( isset( $pll_tc_options['tc_front_slider'] ) )
        pll_register_string( 'Front page slider name', esc_attr($pll_tc_options['tc_front_slider']), $polylang_group );
    
    // Add archive title strings to Polylang's string translation panel
    foreach ( $pll_tc_archive_titles as $opt => $name )
        if ( isset( $pll_tc_options["tc_{$opt}_title"] ) )
            pll_register_string( $name, esc_attr($pll_tc_options["tc_${opt}_title"]), $polylang_group );
}
// front add_filters hooked to 'after_setup_theme' since, when the theme is Customizr-pro, FPU is fired with it
add_action('after_setup_theme', 'perform_pll');
function perform_pll(){
    // If Polylang is active, translate/swap featured page buttons/text/link and slider
    if ( function_exists( 'pll_get_post' ) && function_exists( 'pll__' ) ) {

        $pll_tc_archive_titles = array( 'tag_archive', 'category_archive', 'author_archive', 'search_results');
 
        // Set hook prefix if running FPU. If not, default to Customizr. (Hooks won't be called anyway if neither is running)
        $pll_tc_hook_prefix = ( class_exists( 'TC_fpu' ) ) ? 'fpc_' : 'tc_fp_';
        // Substitute any page id with the equivalent page in current language (if found)
        add_filter( $pll_tc_hook_prefix.'id', 'pll_tc_page_id' );
        function pll_tc_page_id( $fp_page_id ) {
     
            return is_int( pll_get_post( $fp_page_id ) ) ? pll_get_post( $fp_page_id ) : $fp_page_id;
     
        }
     
        // Substitute the featured page button text with the current language button text
        add_filter( $pll_tc_hook_prefix.'button_text', 'pll__' );
     
        // Substitute the featured page text with the translated featured page text
        add_filter( $pll_tc_hook_prefix.'text', 'pll__' );
     
        // Substitute any registered slider name
        add_filter( 'tc_slider_name_id', 'pll__' );

        foreach ( $pll_tc_archive_titles as $title )
            add_filter("tc_{$title}_title", 'pll__' , 20);

    }
}

 

 

Translate text

Once you have installed the Customizr-Polylang bridge code, Customizr’s featured pages text and buttons will be available for translation in Polylang, together with the slider names. Tip: The featured pages button text will only be available for translation if you have entered some text in the Button text field in Appearance > Customize > Front page > Featured pages options.

In Polylang’s settings (in Settings > Languages), choose the String translations tab:

1. Translate the featured pages button text into each of your languages;
2. If you have written your own text for the featured pages (which overrides the automatic page excerpts) then the text will appear here and you can translate it for each language. (If you are simply defaulting to the featured pages’ own text, then no text will appear here—the Polylang-Customizr bridge code will tell Customizr which page’s text to use for the excerpt, in the current page’s language.)
3. Enter the name of the slider for each language. For example, if you called your French slider “main-fr-slider”, enter it here in the Français field.
4. Remember to click Save. Tip: Every time you change the featured text in Appearance > Customize, and then translate it in Polylang’s String translation settings tab, Polylang stores the new translation. To save confusion later, select Polylang’s Clean strings translation database option when you save your strings.

 

Uninstalling Polylang

If you decide not to use Polylang, simply deactivate it and delete it. One of the beauties of Polylang is that it uninstalls cleanly. That is, you don’t need to re-edit all your pages as you would, for example, with qTranslate. This goes for this Customizr-Polylang bridge too. Simply remove the code from your child theme’s functions.php.

 

Need help?

If you’ve never used a functions.php file, check out this article. If you need more help, post your question on the WordPress Customizr forum.

Credits: Rocco helped significantly in getting this guide together. Thanks Rocco!

 

Other resources for Polylang

• Polylang vs WPML (french)
• Polylang feature’s overview
• Polylang’s documentation