Function reference

IMPORTANT: when using one or more of these function, you *must* check for the its existence before using it, otherwise your site will badly break with a fatal error at next Polylang update (as WordPress deletes the plugin when updtating it).

pll_the_languages

Displays a language switcher.
Usage:

pll_the_languages($args);

$args is an optional array parameter. Options are:

  • ‘dropdown’ => displays a list if set to 0, a dropdown list if set to 1 (default: 0)
  • ‘show_names’ => displays language names if set to 1 (default: 1)
  • ‘display_names_as’ => either ‘name’ or ‘slug’ (default: ‘name’)
  • ‘show_flags’ => displays flags if set to 1 (default: 0)
  • ‘hide_if_empty’ => hides languages with no posts (or pages) if set to 1 (default: 1)
  • ‘force_home’ => forces link to homepage if set to 1 (default: 0)
  • ‘echo’ => echoes if set to 1, returns a string if set to 0 (default: 1)
  • ‘hide_if_no_translation’ => hides the language if no translation exists if set to 1 (default: 0)
  • ‘hide_current’=> hides the current language if set to 1 (default: 0)
  • ‘post_id’ => if set, displays links to translations of the post (or page) defined by post_id (default: null)
  • ‘raw’ => use this to create your own custom language switcher (default:0)

Important: When using the language switcher as a dropdown, you must provide yourself the action attached to the language switching. If you want the same comportment as provided by the widget, you can find the corresponding code in the file polylang/include/widget.php. You have to output yourself the ul tags if you don’t use the dropdown option.
Examples:

<?php // outputs a list of languages names ?>
<ul><?php pll_the_languages(); ?></ul>

<?php // outputs a flags list (without languages names) ?>
<ul><?php pll_the_languages(array('show_flags'=>1,'show_names'=>0)); ?></ul>

<?php // outputs a dropdown list of languages names ?>
<?php pll_the_languages(array('dropdown'=>1));  ?>

If the options are not enough, you can build your own custom language switcher using the ‘raw’ argument:

$translations = pll_the_languages(array('raw'=>1));

The function will return an array of arrays, one array per language with the following entries:

  • [id] => language id
  • [slug] => language code used in urls
  • [name] => language name
  • [url] => url of the translation
  • [flag] => url of the flag
  • [current_lang] => true if this is the current language, false otherwise
  • [no_translation] => true if there is no available translation, false otherwise

pll_current_language

Returns the current language
Usage:

pll_current_language($value);
  • ‘$value’ => (optional) either ‘name’ or ‘locale’ or ‘slug’, defaults to ‘slug’

returns either the full name, or the WordPress locale (just as the WordPress core function ‘get_locale’ or the slug ( 2-letters code) of the current language.

pll_default_language

Returns the default language
Usage:

pll_default_language($value);
  • ‘$value’ => (optional) either ‘name’ or ‘locale’ or ‘slug’, defaults to ‘slug’

returns either the full name, or the WordPress locale (just as the WordPress core function ‘get_locale’ or the slug ( 2-letters code) of the current language.

pll_get_post

Returns the post (or page) translation
Usage:

pll_get_post($post_id, $slug);
  • ‘$post_id’ => (required) id of the post you want the translation
  • ‘$slug’ => (optional) 2-letters code of the language, defaults to current language

returns the id of the translated post or page as integer.

pll_get_term

Returns the category (or post tag) translation
Usage:

pll_get_term($term_id, $slug);
  • ‘$term_id’ => (required) id of the term you want the translation
  • ‘$slug’ => (optional) 2-letters code of the language, defaults to current language

returns the id of the translated term as integer.

pll_is_front_page (deprecated)

Removed in v0.8.2 as it is now useless. Use the standard WP is_front_page function instead.

pll_home_url

Returns the home page url
Usage:

pll_home_url($slug);
  • ‘$slug’ => 2-letters code of the language. The parameter is optional and defaults to the current language if the function is called on frontend.

returns the url of the homepage in the requested language, as a string.

pll_register_string

Allows plugins to add their own strings in the “strings translation” panel. The function must be called on admin side (the functions.php file is OK for themes). It is possible to register empty strings (for example when they come from options) but they won’t appear in the list table.
Usage:

pll_register_string($name, $string, $group, $multiline);
  • ‘$name’ => (required) name provided for sorting convenience (ex: ‘myplugin’)
  • ‘$string’ => (required) the string to translate
  • ‘$group’ => (optional) the group in which the string is registered, defaults to ‘polylang’
  • ‘$multiline’ => (optional) if set to true, the translation text field will be multiline, defaults to false

pll__

translates a string previously registered with pll_register_string
Usage:

pll__($string);

The unique parameter is required:

  • ‘$string’ => the string to translate

returns the translated string.

pll_e

Echoes a translated string previously registered with pll_register_string
Usage:

pll_e($string);

The unique parameter is required:

  • ‘$string’ => the string to translate

pll_translate_string

Translates a string previously registered with pll_register_string in a given language. Unlike ‘pll__()’ and ‘pll_e()’ which allow to get the translation only in the current language (as do the WordPress localization functions ‘__()’ and ‘_e()’), this function allows to get the translation in any language.
Usage:

pll_translate_string($string, $lang);
  • ‘$string’ => the string to translate
  • ‘$lang’ => the language code of the desired translation

returns the translated string.

pll_is_translated_post_type

Returns true if Polylang manages languages and translations for this post type, false otherwise
Usage:

pll_is_translated_post_type($post_type);

The unique parameter is required:

  • ‘$post_type’ => the post type to check

pll_is_translated_taxonomy

Returns true if Polylang manages languages and translations for this taxonomy, false otherwise
Usage:

pll_is_translated_taxonomy($tax);

The unique parameter is required:

‘$tax’ => the taxonomy to check

pll_languages_list

Returns the list of languages
Usage:

pll_languages_list($args);

$args is an optional array parameter. Options are:

  • ‘hide_empty’ => hides languages with no posts if set to 1 (default: 0)
  • ‘fields’ => returns only that field if set. Possible values are ‘slug’, ‘locale’, ‘name’, defaults to ‘slug’

pll_get_post_language

gets the language of a post or page (or custom post type post)
Usage:

pll_get_post_language($post_id, $field);
  • ‘$post_id’ => (required) id of the post for which you want to get the language
  • ‘$field’ => (optional) either ‘name’ or ‘locale’ or ‘slug’, defaults to ‘slug’

returns either the full name, or the WordPress locale or the slug ( 2-letters code) of the post.

pll_get_term_language

gets the language of a category or post tag (or custom taxonomy term)
Usage:

pll_get_term_language($term_id, $field);
  • ‘$term_id’ => (required) id of the term for which you want to get the language
  •  ‘$field’ => (optional) either ‘name’ or ‘locale’ or ‘slug’, defaults to ‘slug’

returns either the full name, or the WordPress locale or the slug ( 2-letters code) of the term.

pll_set_post_language

Sets the language of a post or page (or custom post type post)
Usage:

pll_set_post_language($post_id, $lang);
  • ‘$post_id’ => (required) id of the post for which you want to set the language
  • ‘$lang’ => (required) language code

pll_set_term_language

Sets the language of a category or post tag (or custom taxonomy term)
Usage:

pll_set_term_language($term_id, $lang);
  • ‘$term_id’ => (required) id of the term for which you want to set the language
  • ‘$lang’ => (required) language code

pll_save_post_translations

Defines which posts are translations of each other
Usage:

pll_save_post_translations($arr);
  • ‘$arr’ => (required) associative array of translations with language code as key and post id as value

pll_save_term_translations

Defines which terms are translations of each other
Usage:

pll_save_term_translations($arr);
  • ‘$arr’ => (required) associative array of translations with language code as key and term id as value

pll_count_posts

Counts posts in a defined language
Usage:

pll_count_posts($lang, $args);
  • ‘$lang’ => (required) language code
  • ‘$args’ => (optional) allows to restrict the count to a certain class of post archive. Accepted keys are ‘post_type’, ‘m,’ ‘year’, ‘monthnum’, ‘day’, ‘author’, ‘author_name’, ‘post_format’