Filter reference

pll_copy_post_metas

Allows plugins to copy custom fields when a new post (or page) translation is created or synchronizing them. Filter arguments:

  • $metas => an array of post metas
  • $sync => false when copying custom fields to a new translation, true when synchronizing translations
  • $from => Id of the post from which we copy informations
  • $to => Id of the post to which we paste informations
  • $lang => Language slug

Example:

add_filter( 'pll_copy_post_metas', 'copy_post_metas' );

function copy_post_metas( $metas ) {
	return array_merge( $metas, array( 'my_post_meta' ) );
}

pll_translate_post_meta

Allows plugins to modify custom fields when it is copied from one post to a translation. This is typically used in combination with `pll_copy_post_metas’ to translate the custom field. Filter arguments:

  • $value => Meta value
  • $key => Meta key
  • $lang => Language slug of the target post
  • $from => Id of the post from which we copy informations
  • $to => Id of the post to which we paste informations

Example:

add_filter( 'pll_translate_post_meta', 'translate_post_meta', 10, 3 );

function translate_post_meta( $value, $key, $lang ) {
	if ( '_thumbnail_id' === $key ) {
			$value = pll_get_post( $value, $lang );
	}
	return $value;
}

pll_copy_term_metas

Allows plugins to copy term metas when a new term translation is created or synchronizing them. The usage is similar to the filter ‘pll_copy_post_metas’.

pll_translate_term_meta

Allows plugins to modify term metas when it is copied from one term to a translation. This is typically used to translate the term meta. The usage is similar to the filter ‘pll_translate_post_meta’.

pll_copy_taxonomies

Allows plugins to copy taxonomy terms when a new post (or page) translation is created or synchronize them. Filter arguments:

  • $taxonomies => list of taxonomy names
  • $sync => true if it is synchronization, false if it is a copy
  • $from => Id of the post from which we copy informations
  • $to => Id of the post to which we paste informations
  • $lang => Language slug

Example:

add_filter( 'pll_copy_taxonomies', 'copy_tax', 10, 2 );

function copy_tax( $taxonomies, $sync ) {
	$taxonomies[] = 'my_custom_tax';
	return $taxonomies;
}

pll_translation_url

Allows plugins to modify (or create) the translation url. This is thus a more generic filter than ‘pll_the_languages_link’ described below. Filter arguments:

  • $url => the translation URL to modify (set to null if there is no translation available)
  • $slug => the 2-letters language iso-code of the translation

Allows plugins to modify the translation link outputed by the language switcher (valid for the widget, the nav menus and the function pll_the_languages). Filter arguments:

  • $url => the translation URL to modify (set to null if there is no translation available)
  • $slug => the 2-letters language iso-code of the translation
  • $locale => the WordPress locale for the language of the translation

Example (to link to the posts list in the right language when there is no translation available):

add_filter( 'pll_the_language_link', 'my_link', 10, 2 );

function my_link( $url, $slug ) {
	return $url === null ? home_url( '?lang=' . $slug ) : $url;
}

pll_flag_title

Allows plugins to modify the title attribute of the flag in the language switcher (defaults to language name). Filter arguments:

  • $title => the title attribute
  • $slug => the 2-letters language iso-code of the translation
  • $locale => the WordPress locale for the language of the translation

Example:

add_filter( 'pll_flag_title', 'my_flag_title', 10, 2 );

function my_flag_title( $title, $slug ) {
	switch( $slug ) {
		case 'en':
			return 'The blog in ' . $title;
		break;
		case 'fr':
			return 'Le blog en ' . $title;
		break;
		default:
			return $title;
		break;
	}
}

pll_the_languages

Allows plugins to modify the whole output of the language switcher. Filter arguments:

  • $output => the output of the language filter
  • $args => the arguments of the function pll_the_languages

Example (to add a link to the flag file in the title attribute of the dropdown list which maybe useful used together with a script adding a picture in the dropdown):

add_filter( 'pll_the_languages', 'my_dropdown', 10, 2 );

function my_dropdown( $output, $args ) {
	if ( ! $args['dropdown'] ) {
		return $output;
	}
	foreach ( array( 'en_US', 'fr_FR', 'de_DE' ) as $lang ) {
		$file = POLYLANG_DIR . "/flags/$lang.png";
		$value = reset( explode( '_', get_locale() ) );
		$output = str_replace( "value='$value'", "value='$lang' title='$file'", $output );
	}
	return $output;
}

pll_the_languages_args

Allows plugins to filter the arguments passed to the function pll_the_languages used to display a language switcher. Filter arguments:

  • $args => the arguments of the function pll_the_languages

Example (to display the language code instead of the language native name in the language switcher):

add_filter( 'pll_the_languages_args', 'my_language_switcher_args' );

function my_language_switcher_args( $args ) {
	$args['display_names_as'] = 'slug';
	return $args;
}

pll_get_post_types

Allows plugins to modify the list of post types which will be filtered by language. The default are custom post types which have the parameter ‘public’ set to true. The filter must be added soon in the WordPress loading process: in a function hooked to ‘plugins_loaded’ or directly in functions.php for themes. Filter arguments:

  • $post_types => the array of post type names
  • $is_settings => true when displaying the list of custom post types in Polylang settings (avoid the user to modify the decision made by the plugin author for a post type)

Example:

add_filter( 'pll_get_post_types', 'add_cpt_to_pll', 10, 2 );

function add_cpt_to_pll( $post_types, $is_settings ) {
	if ( $is_settings ) {
		// hides 'my_cpt' from the list of custom post types in Polylang settings
		unset( $post_types['my_cpt'] );
	} else {
		// enables language and translation management for 'my_cpt'
		$post_types['my_cpt'] = 'my_cpt';
	}
	return $post_types;
}

pll_get_taxonomies

Allows plugins to modify the list of taxonomies which will be filtered by language. The default are taxonomies which have the parameter ‘public’ set to true (which include categories and post tags). The filter must be added soon in the WordPress loading process: in a function hooked to ‘plugins_loaded’ or directly in functions.php for themes. Filter arguments:

  • $taxonomies => the array of taxonomy names
  • $is_settings => true when displaying the list of custom taxonomies in Polylang settings (avoid the user to modify the decision made by the plugin author for a taxonomy)

Example:

add_filter( 'pll_get_taxonomies', 'add_tax_to_pll', 10, 2 );

function add_tax_to_pll( $taxonomies, $is_settings ) {
	if ( $is_settings ) {
		unset( $taxonomies['my_tax'] );
	} else {
		$taxonomies['my_tax'] = 'my_tax';
	}
	return $taxonomies;
}

pll_rewrite_rules

Allows plugins to inform Polylang of a new rewrite rules filter to use (allowing this rules to be filtered by language. Filter arguments:

  • $rules => the array rewrite rules to filter

Example:

// create rewrite rules with a filter 'something_rewrite_rules'
add_filter( 'generate_rewrite_rules', 'my_rules' );

function my_rules( $wp_rewrite ) {
	$rules[] = ...
	$rules = apply_filters( 'my_own_rewrite_rules', $rules );
	$wp_rewrite->rules = array_merge( $rules, $wp_rewrite->rules );
}
// add the filter (without '_rewrite_rules') to the Polylang list
add_filter( 'pll_rewrite_rules', function( $rules ) {
	return array_merge( $rules, array( "my_own" ) );
 } );

pll_preferred_language

Allows plugins to modify the visitor preferred language (normally set first by cookie if this is not the first visit, then by the browser preferences). If no preferred language has been found or set by this filter, Polylang fallbacks to the default language. Filter arguments:

  • $slug => language code or false if no preferred language has been found

Example:

// fallback language is English whatever the default language
add_filter( 'pll_preferred_language', 'my_language_fallback' );

function my_language_fallback( $slug ) {
	return $slug === false ? 'en' : $slug;
}

pll_get_flag

Allows plugins to modify the html output of flags (the images). Filter arguments:

  • $flag => html output of one flag
  • $slug => language code

Example:

// displays language code instead of flags on admin side
add_filter( 'pll_get_flag', 'no_flag_on_admin' );

function no_flag_on_admin( $flag ) {
	return is_admin() ? '' : $flag;
}

pll_redirect_home

When a visitor reaches the home, Polylang redirects to the home in the correct language. This filter allows plugins to modify the redirected url or prevent this redirection. Filter arguments:

  • $redirect => the redirected url. If set to false, there will be no redirection.

Example:

// prevents home redirection
add_filter( 'pll_redirect_home', '__return_false' );

Note: You must add this filter in a custom plugin as it is generally applied before the theme is loaded.

pll_sanitize_string_translation

Allows to sanitize strings registered with pll_register_string. Filter arguments:

  • $string => the translated string to sanitize
  • $name => string name
  • $group => the group in which the string is registered

Allows to modify the cookie duration. Filter arguments:

  • $duration => the cookie duration in seconds. Defaults to one year

Note: You must add this filter in a custom plugin as it is generally applied before the theme is loaded.

pll_rel_hreflang_attributes

Allows to modify hreflang attributes displayed in the html head on frontend. Filter arguments:

  • $hreflangs => Array of urls with language codes as keys and links as values

Examples:

// Adds English as 'x-default' on all pages.
add_filter( 'pll_rel_hreflang_attributes', function( $hreflangs ) {
	$hreflangs['x-default'] = $hreflangs['en'];
	return $hreflangs; // Array of urls with language codes as keys and links as values.
} );

// Replaces 'en' by 'en-GB' on all pages.
add_filter( 'pll_rel_hreflang_attributes', function( $hreflangs ) {
	$hreflangs['en-GB'] = $hreflangs['en'];
	unset( $hreflangs['en'] );
	return $hreflangs;
} );

pll_custom_flag

Allows to modify a flag url and size. Filter arguments:

  • $flag => An array of information with ‘url’,’src’, height’, ‘width’ keys. The url is mandatory. The 3 other parameters are optional. The ‘height’ and ‘width’ parameters are especially useful for SVG flags.
  • $code => Flag code

Notes:

  • The filter needs to be added in a plugin or mu-plugin before the action ‘plugins_loaded’ has been fired. It can’t work in the functions.php of a theme.
  • The filter acts only on flags displayed on frontend. The flags used in the backend are kept unchanged.
  • After you have changed the code in the filter, go to Languages > Settings. Click on the “URL modifications” settings and then on Save Changes, to reset the transient storing the languages.

Example:

add_filter( 'pll_custom_flag', 'pll_custom_flag', 10, 2 );

function pll_custom_flag( $flag, $code ) {
	$flag['url']    = content_url( "/polylang/{$code}.svg" );
	$flag['width']  = 32;
	$flag['height'] = 22;
    $flag['src'] = '';
	return $flag;
}

pll_flag

This filter works the same as ‘pll_custom_flag’ except that it acts both on frontend and backend.

pll_pre_current_user_can_synchronize_post

Used to decide if a synchronizations capability check should take place when a user doesn’t have the right to edit one of the translated posts. Filter arguments:

  • $check => null to enable the capability check, true to allow the synchronization, false to disallow the synchronization. Defaults to true.
  • $post_id => Id of the synchronization source post.

Example:

add_filter( 'pll_pre_current_user_can_synchronize_post', '__return_null' );