Function reference

IMPORTANT: when using one or more of these function, you *must* check for 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 updating it).

pll_the_languages()

Displays a language switcher on the frontend.

Important: before calling this function (or any Polylang API), check that it exists, or your site can fatally error when Polylang is deactivated or during an update:

if ( function_exists( 'pll_the_languages' ) ) {
	pll_the_languages();
}

The function does nothing in the admin and when Polylang’s link layer is not loaded (it returns an empty string, or an empty array with raw).

Usage

pll_the_languages( $args );

$args is an optional array.

Arguments

Options are:

• layout => (string) switcher layout: horizontal, vertical, dropdown, or select (default: vertical)
• alignment => (string) left, center, right, stretched, or inherit (default: left or right, depending on is_rtl())
• show_wrapper => (bool) whether to output the outer wrapper (default: true)
• show_flags => (bool) display flags (default: false)
• flag_aspect_ratio => (string) 3:2 or 1:1 (default: 3:2)
• show_labels => (string) '' (no labels), names (language names), or codes (language codes) (default: names)
• hide_if_empty => (bool) hide languages with no posts or pages (default: true)
• hide_if_no_translation => (bool) hide languages with no translation for the current context or post_id (default: false)
• hide_current => (bool) hide the current language (default: false)
• force_home => (bool) link each language to its homepage instead of the translation URL (default: false)
• post_id => (int) build links from translations of this post or page ID (default: 0)
• preserve_spacing => (bool) preserve whitespace between list items in HTML output (default: true)
• wrapper_classes => (array) extra CSS classes on the wrapper (default: empty array)
• item_classes => (array) extra CSS classes on each language item (default: empty array)
• link_classes => (array) extra CSS classes on each link (default: empty array)
• unique_id => (string) HTML id for the switcher; auto-generated if empty (default: empty string)
• echo => (bool) echo HTML if true, return HTML if false (ignored when raw is true) (default: true)
• raw => (bool) return a data array instead of HTML (default: false)

Layouts

• vertical / horizontal: list inside a <nav> when show_wrapper is true
• dropdown: dropdown built from links (not a native <select>)
• select: native <select>; since 3.9 each <option> value is a URL

Return value

• Default (echo => true, raw => false): prints HTML (void)
• echo => false, raw => false: returns HTML as a string
• raw => true: returns an array keyed by language slug

Examples

Vertical list with names (default settings):

pll_the_languages();

Flags only (no names):

pll_the_languages(
	array(
		'show_flags'             => true,
		'show_labels'            => '',
	)
);

Language codes instead of full names:

pll_the_languages(
	array(
		'show_labels'            => 'codes',
	)
);

Horizontal list with flags and names:

pll_the_languages(
	array(
		'layout'                 => 'horizontal',
		'show_flags'             => true,
	)
);

Select switcher:

pll_the_languages(
	array(
		'layout'                 => 'select',
	)
);

Return HTML instead of echoing:

$html = pll_the_languages(
	array(
		'echo'                   => false,
	)
);

Links for translations of a specific post:

pll_the_languages(
	array(
		'post_id'                => 123,
	)
);

Hide languages without a translation:

pll_the_languages(
	array(
		'hide_if_no_translation' => true,
	)
);

Custom switcher (raw)

$languages = pll_the_languages( array( 'raw' => true ) );

Each entry is keyed by language slug (en, fr, …). Fields include:

• id              => language term ID
• slug            => URL language code
• locale          => WordPress locale
• name            => display name (or code if show_labels is codes)
• label           => label used for the item
• url             => target URL for this language
• flag            => flag image URL
• direction     => ltr or rtl
• is_rtl          => boolean
• is_current      => current language on this request
• has_translations => translation exists for the current context
• is_empty        => no posts in this language (when relevant)
• order           => sort order
• item_classes    => CSS classes for the item
• link_classes    => CSS classes for the link
• current_lang    => deprecated alias of is_current
• no_translation  => deprecated; opposite of has_translations
• classes         => deprecated alias of item_classes

Filter

Since 3.9, switcher settings can be filtered with pll_language_switcher_settings. The filter pll_the_languages_args is deprecated since 3.9.

add_filter(
	'pll_language_switcher_settings',
	function ( $settings ) {
		return $settings;
	}
);

Backend and language lists

pll_the_languages() is meant to display a switcher on the frontend. It is not intended for the admin.

To list configured languages without rendering a switcher, use pll_languages_list() instead.

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_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_get_post_translations()

Returns an associative array of translations with language code as key and translation post_id as value
Usage:

pll_get_post_translations( $post_id );

• ‘$post_id’ => (required) id of the post for which you want to get the translations

pll_get_term_translations()

Returns an associative array of translations with language code as key and translation term_id as value
Usage:

pll_get_term_translations( $term_id );

• ‘$term_id’ => (required) id of the term for which you want to get the translations

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’

pll_insert_post()

Wraps wp_insert_post() with language features. Since Polylang 3.7.

Usage:

pll_insert_post( $postarr, $language);

• $postarr => (required) An array of elements that make up a post to insert. See wp_insert_post() for arguments.
  • $translations => The translation group to assign to the post with language slug as keys and post ID as values.
• $language =>(required) The post language object or slug.

Returns the created post_id on success or a WP_ERROR on failure.

	pll_insert_post(
		array(
			'post_title'   => 'My Content',
			'post_content' => 'This is my content',
			'post_status'  => 'publish',
			'post_type'    => 'post',
            'translations' => array( 'fr' => 14, 'ar' => 23 ),   
			),
		'en'
	)

pll_update_post()

Wraps `wp_update_post` with language feature. Since Polylang 3.7.

Usage:

pll_update_post( $postarr );

• $postarr => An array of elements that make up a post to update. See wp_insert_post() for arguments.
  • $lang => The post language object or slug.
  • $translations => The translation group to assign to the post with language slug as keys and post ID as values.

	$postarr = array(
		'ID'           => 83,
		'post_title'   => 'My Content modified',
		'lang'         => 'en',
		'translations' => array(
			'fr'   => 79,
			'it'   => 85,
		)
	);

	pll_update_post( $postarr );

pll_insert_term()

Wraps `wp_insert_term` with language feature. Since Polylang 3.7.

Usage:

pll_insert_term( $term, $taxonomy, $language, $args );

• $term => The term name to add.
• $taxonomy => The taxonomy to which to add the term.
• $language => The term language object or slug.
• $args => Array of arguments for inserting a term. (Optional)
  • $alias_of => Slug of the term to make this term an alias of. Default empty string. Accepts a term slug.
  • $description => The term description. Default empty string.
  • $parent => The id of the parent term. Default 0.
  • $slug => The term slug to use. Default empty string.
  • $translations => The translation group to assign to the term with language slug as keys and `term_id` as values (array).

Returns an array of the new term data or WP_ERROR.

	pll_insert_term( 'My term', 'category', 'en' );	

pll_update_term()

Wraps `wp_update_term` with language feature. Since Polylang 3.7.

Usage:
pll_update_term( $term_id, $args );

• $term_id =>The ID of the term.
• $args => Array of arguments for updating a term.
  • $alias_of => Slug of the term to make this term an alias of. Default empty string. Accepts a term slug.
  • $description => The term description. Default empty string.
  • $parent => The id of the parent term. Default 0.
  • $slug => The term slug to use. Default empty string.
  • $name => The term name.
  • $lang => The term language object or slug.
  • $translations => The translation group to assign to the term with language slug as keys and term_id as values (array).

Returns an array containing the term_id and term_taxonomy_id, WP_Error otherwise.

	pll_update_term(
		 82,
		 array(
			'slug'         => 'my-slug',
			'translations' => array(
				'fr'   => 86,
				'it'   => 88,
			)
		 ),
	);