How to

How to know the current language in the theme ?

WordPress provides at least two functions for the themes or plugins authors to know the current language:

  • get_locale() returns the WordPress locale in the format 'en_US'
  • get_bloginfo('language') returns the locale in the format 'en-US'

Note the difference between '_' and '-' in the two functions. You can have a look at the following forum topics:

Additionaly, Polylang now provides the function 'pll_current_language' which can return either the language code, the locale or the language name.

How to make translatable user defined strings in my plugin or theme ?

You have to register strings on the admin side with the function 'pll_register_string' and display them on frontend with 'pll__' or 'pll_e'.

How to make my custom post types and taxonomies multilingual?

You must register your custom post type (or taxonomy) in a function hooked to the 'init' action as usual.
The user will have access to an option to enable languages and translations for the custom post type (or taxonomy) in the Polylang settings. You can however use the 'pll_get_post_types' or 'pll_get_taxonomies' filters to get full control on this.

How to query content in a different language than the current one?

Polylang does set the language of the theme based on the main query, but it is possible to query content in a different language. For example, you can display the list of the five most recent French posts on an English page. Your custom query just needs to add the 'lang' parameter.
Example:

$posts = get_posts( array(
	'post_type' => 'post',
	'lang' => 'fr', // use language slug in the query
	'showposts' => 5,
) );

This 'lang' parameter is not only available for posts but also for terms using the function 'get_terms' and comments using the function 'get_comments'.

How to query multiple languages?

Example:

$posts = get_posts( array(
	'post_type' => 'post',
	'lang' => 'de,fr', // query German and French posts
	'showposts' => 5,
) );

How to deactivate the current language filter?

Example:

$posts = get_posts( array(
	'post_type' => 'post',
	'lang' => '', // deactivates the Polylang filter
	'showposts' => 5,
) );

Example:

<?php while ( have_posts() ) : the_post(); ?>
<ul class='translations'><?php pll_the_languages( array( 'post_id' => $post->ID ) ); ?></ul>
<?php the_content(); ?>
<?php endwhile; ?>

How to load the Polylang API for ajax requests on frontend ?

Polylang should automatically detect AJAX requests on frontend and load the current language. You can optionally set the 'lang' variable (with the language code) in the request (POST or GET) to load a specific language instead of the current language. The variable 'pll_load_front' which was necessary in old versions is useless since v1.4.

When Polylang does load the language?

There are two cases:

  1. The language is set from the content: Polylang needs to defer the language loading and does it in a function hooked to the action 'wp' action with priority 5.
  2. The language code is added to all urls (default): there is no need to defer the language loading and it is done as if Polylang were not active.

Due to the first case, plugin authors should not attempt to translate strings before the 'wp' action has been fired. Polylang provides a new action 'pll_language_defined' which is fired as soon as the language is defined. It works whatever the option chosen by the user to set the language.

How to give access to strings translations to non-administrators?

As the main purpose of the strings translations is to translate options, Polylang checks for the ‘manage_options’ capability, which is assigned to administrators by default, to control the access to the strings translations table. You can modify the required capability with the following snippet:

add_action( 'admin_menu', function() {
	if ( ! current_user_can( 'manage_options' ) && function_exists( 'PLL' ) ) {
		add_menu_page( __( 'Strings translations', 'polylang' ), __( 'Languages', 'polylang' ), 'edit_pages', 'mlang_strings', array( PLL(), 'languages_page' ), 'dashicons-translation' );
	}
} );

Here the capability was changed to ‘edit_pages’, which is assigned to administrators and editors by default. See the codex to discover which capability you can use to target other roles.