All hooks listed in this API are available for WPML versions >=3.2

Site-Wide Language Information

wpml_browser_redirect_language_params – Filters the $params argument which is an associative array that contains information about the current language

availability:
WPML Version: Comming soon!
description:

This filter can be used when the theme developer wants to use a different cookie name or tweak the languageUrls array to use different URLs.

It uses the $params argument which is an associative array containing some information about the current language, the active languages and the cookie settings.

type:
filter
category:
Site-Wide Language Information
parameters:
pageLanguage
Stores the current language code.
languageUrls
Stores an associative array containing all the current page’s translation URLs. The keys of the array are the language codes. The same language can have multiple entries to match a different combination of language codes. For instance, in the case of en_US, the same URL is repeated three times with the following keys: en_us, en, and us.
cookie
Stores an associative array with the cookie settings. Please refer to Document.cookie for more details. The keys are:

  • name: the name of the cookie (defaults to _icl_visitor_lang_js).
  • domain: the domain in which the cookie must be used (defaults to the current domain and is not meant to be changed).
  • path: the path of the cookie (defaults to /).
  • expiration: the expiration in seconds is read from the value set in Remember visitors’ language preference that can be found in Browser language redirect on the WPML -> Languages.
hook example usage:

In order to use this filter Browser language redirect must be enabled on the WPML -> Languages.

The following code can be used to disable the redirect feature on a specific page:

function example( $enqueue ) {
    global $post;
    // Do not enqueue the scripts if the page ID is 123
    if ( $post->ID === 123 ) {
        $enqueue = false;
    }

    return $enqueue;
}

add_filter( 'wpml_enqueue_browser_redirect_language', 'example' );
Back to the top

wpml_active_languages – Get a list of the languages enabled for a site

availability:
WPML Version: 3.2
description:

Filters the list of the languages enabled (active) for a site. This filter is usually used to create custom language switchers.

This filter can only work when the global $wp_query object has been instantiated. This means that it should be called after the wp action happens.

WPML returns a site’s active (enabled) languages as an array with relative information per language. For example, for a WordPress site running English, French and Italian, the hook will return this:

Array
(
 [en] => Array
  (
   [id] => 1
   [active] => 1
   [native_name] => English
   [missing] => 0
   [translated_name] => English
   [language_code] => en
   [country_flag_url] => http://yourdomain/wpmlpath/res/flags/en.png
   [url] => http://yourdomain/about
  )

 [fr] => Array
  (
   [id] => 4
   [active] => 0
   [native_name] => Français
   [missing] => 0
   [translated_name] => French
   [language_code] => fr
   [country_flag_url] => http://yourdomain/wpmlpath/res/flags/fr.png
   [url] => http://yourdomain/fr/a-propos
  )

 [it] => Array
  (
   [id] => 27
   [active] => 0
   [native_name] => Italiano
   [missing] => 0
   [translated_name] => Italian
   [language_code] => it
   [country_flag_url] => http://yourdomain/wpmlpath/res/flags/it.png
   [url] => http://yourdomain/it/circa
  )
)

The wpml_active_languages filter provides a way to do things like reorder the language array. Or something more complex, like redirecting missing languages to a custom url.

type:
filter
category:
Site-Wide Language Information
parameters:
apply_filters( 'wpml_active_languages', mixed $empty_value, array|string $args )
$empty_value
(mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
$args
(array|string) (Optional) Arguments to filter the language output

  • skip_missing(bool) How to treat languages with no translations. 1 to skip language or 0 to link to home of language for missing translations.
  • link_empty_to(string) Works in conjunction with skip_missing = 0 and allows using custom links for the languages that do not have translations for the current element. {%lang} can be used as placeholder for the language code. Empty by default.
  • orderby(string) Accepts id|code|name Defaults to custom. The custom order can be defined in the WordPress admin under WPML » Languages » Language Switcher Options
  • order(string) Accepts asc|desc
hook example usage:

The filter’s arguments can be passed to it as a string as shown in the first example below. They can also be passed as an array as you can see in the second example further down.

In the example below we display a flag only language switcher. However, there is a small difference to the flag-only language switcher you can configure from your “WPML language settings” in the admin backend.

The difference here is that the current language will not be wrapped inside an anchor. Only the page’s alternative languages will have a link. Have a look.

Example

function my_flag_only_language_switcher() {
    $languages = apply_filters( 'wpml_active_languages', NULL, 'orderby=id&order=desc' );

    if ( !empty( $languages ) ) {
        foreach( $languages as $l ) {
            if ( !$l['active'] ) echo ' <a href="' . $l['url'] . '">';
            echo '<img src="' . $l['country_flag_url'] . '" height="12" alt="' . $l['language_code'] . '" width="18" />';
            if ( !$l['active'] ) echo '</a> ';
        }
    }
}

In the next example you see below, we redirect missing languages to a custom page where we display a contact form for people to notify the site admin of untranslated content.
We also capitalize the language name of the active language i.e. the language we are currently viewing, using PHP’s strtoupper function.

A second example

function my_custom_language_switcher() {
    $languages = apply_filters( 'wpml_active_languages', NULL, array( 'skip_missing' => 0, 'link_empty_to' => 'http://domain.com/missing-translation-contact-form' ) );

    if( !empty( $languages ) ) {
        foreach( $languages as $language ){
			$native_name = $language['active'] ? strtoupper( $language['native_name'] ) : $language['native_name'];

            if( !$language['active'] ) echo '<a href="' . $language['url'] . '">';
            echo $native_name . ' ';
            if( !$language['active'] ) echo '</a>';
        }
    }
}
Back to the top

wpml_encode_string – Encode fields that are in a format that WPML does not understand

availability:
WPML Version: Comming soon!
description:

Custom fields can be encoded in a format that WPML does not understand. Those fields have to be decoded and encoded before WPML can translate them. To achieve this, the wpml_decode_custom_field and wpml_encode_custom_field filters must be used. These filters can be used if there is additional custom encoding besides the ones already handled by WPML.

type:
filter
category:
Site-Wide Language Information
parameters:
apply_filters( $custom_field_val, $custom_field_name )
$custom_field_val
Value contained within field that needs to be encoded
$custom_field_name
Name of the field that needs to be encoded
hook example usage:

To encode custom field use following code:

add_filter( 'wpml_encode_custom_field', 'my_encode_function', 10, 2 );

function my_encode_function( $custom_field_val, $custom_field_name ) {
   if ( $custom_field_name === 'my-special-field' ) {
      $custom_field_val = my_special_encoding_function( $custom_field_val );
   }
}
Back to the top

wpml_decode_string – Decode fields that are in a format that WPML does not understand

availability:
WPML Version: Comming soon!
description:

Custom fields can be encoded in a format that WPML does not understand. Those fields have to be decoded and encoded before WPML can translate them. To achieve this, the wpml_decode_custom_field and wpml_encode_custom_field filters must be used. These filters can be used if there is additional custom encoding besides the ones already handled by WPML.

type:
filter
category:
Site-Wide Language Information
parameters:
apply_filters( $custom_field_val, $custom_field_name )
$custom_field_val
Value contained within field that needs to be decoded
$custom_field_name
Name of the field that needs to be decoded
hook example usage:

To decode a custom field use following code:

add_filter( 'wpml_decode_custom_field', 'my_decode_function', 10, 2 );

function my_decode_function( $custom_field_val, $custom_field_name ) {
   if ( $custom_field_name === 'my-special-field' ) {
      $custom_field_val = my_special_decoding_function( $custom_field_val );
   }
}
Back to the top

wpml_display_language_names – Get a language's native and translated name for display in a custom language switcher

availability:
WPML Version: 3.2
description:

Checks if the native name of a language and the translated name of the same language are different. If so, it returns them both. Otherwise, it returns only one.
This filter is usually used in custom language switchers.

type:
filter
category:
Site-Wide Language Information
parameters:
apply_filters( 'wpml_display_language_names', mixed $empty_value, string $native_name, string|bool $translated_name, bool $lang_native_hidden, bool $lang_translated_hidden )
$empty_value
(mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
$native_name
(string) (Required) The language native name
$translated_name
(string|bool) (Required) The language translated name Defaults to FALSE
$lang_native_hidden
(bool) (Optional) Default is FALSE 0|false or 1|true Whether to hide the language native name or not
$lang_translated_hidden
(bool) (Optional) Default is FALSE 0|false or 1|true Whether to hide the language translated name or not
hook example usage:

Example

function my_footer_languages_list(){
    $languages = apply_filters( 'wpml_active_languages', NULL, 'skip_missing=0&orderby=code' );
    if( !empty( $languages ) ){
        echo '<div id="footer_language_list"><ul>';
        foreach( $languages as $l ){
            echo '<li>';
            if( $l['country_flag_url'] ){
                if( !$l['active'] ) echo '<a href="'.$l['url'].'">';
                echo '<img src="'.$l['country_flag_url'].'" height="12" alt="'.$l['language_code'].'" width="18" />';
                if( !$l['active'] ) echo '</a>';
            }
            if(!$l['active']) echo '<a href="'.$l['url'].'">';
            echo apply_filters( 'wpml_display_language_names', NULL, $l['native_name'], $l['translated_name'] );
            if( !$l['active'] ) echo '</a>';
            echo '</li>';
        }
        echo '</ul></div>';
    }
}

The example function above does the following:

  1. If there are any languages, it creates a DIV and starts an unordered list
  2. Then it loops through each of the languages and adds it as a list item.
    If the language is not the active language, it adds a link to the translated page for that language
  3. It then adds the language flag
  4. Finally, it adds both the native and translated language names if they’re different
Back to the top

wpml_language_switcher – Display WPML's language switcher

availability:
WPML Version: 3.7.0
description:

Displays the language selector as configured on the WPML -> Languages page.

type:
action
category:
Site-Wide Language Information
parameters:
do_action( 'wpml_language_switcher', $args, $twig_template_string );

This action hook has two optional parameters and works as a [wpml_language_switcher] shortcode.

$args

(array) (Optional) Arguments to filter the language switcher output

  • type – Define the language switcher type – footer, post_translations, widget or custom (default).
  • flags (alias for display_flags) – Use 1 to display flags and 0 not to.
  • link_current (alias for display_link_for_current_lang ) – Use 1 to display flags and 0 not to.
  • native (alias for display_names_in_native_lang ) – Use 1 to display flags and 0 not to.
  • translated (alias for display_names_in_current_lang ) – Use 1 to display flags and 0 not to.
  • template – The template slug if it needs to be overwritten. Otherwise it will be defined by the type .
  • For the type, WPML will use the settings on the WPML -> Languages page, from the related sections except for widgets, which will take the default settings for a widget language switcher.
  • We can also pass a Twig template as the content of the shortcode, as shown in the example below. If the Twig template is not valid, the shortcode will not render anything.
  • $twig_template_string

    (string) (Optional)  a Twig template string

    hook example usage:

    Add the code below to your theme template files, where you want the language switcher to be displayed at.

    Example

    do_action( 'wpml_language_switcher', $args, $twig_template_string );

    If you prefer, you can also add the above code line in a PHP widget like PHP Text Widget.

    Back to the top

    wpml_current_language – Get the current display language

    availability:
    WPML Version: 3.2
    description:

    Returns the current language

    type:
    filter
    category:
    Site-Wide Language Information
    parameters:
    apply_filters( 'wpml_current_language', mixed $empty_value )
    $empty_value
    (mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
    hook example usage:

    A basic example

    $my_current_lang = apply_filters( 'wpml_current_language', NULL );
    
    Back to the top

    wpml_is_rtl – Find out whether the current language text direction is RTL or not

    availability:
    WPML Version: 3.2
    description:

    Returns TRUE is the current language is RTL

    type:
    filter
    category:
    Site-Wide Language Information
    parameters:
    apply_filters( 'wpml_is_rtl', mixed $empty_value )
    $empty_value
    (mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
    hook example usage:

    Example

    if ( apply_filters( 'wpml_is_rtl', NULL) ) {
        //Link to RTL CSS stylesheet
    } else {
        //Link to LTR CSS stylesheet
    }
    
    // Alternatively
    
    //Include link to LTR CSS stylesheet here
    
    if ( apply_filters( 'wpml_is_rtl', false ) ) {
        //Link to RTL CSS stylesheet
    }
    
    Back to the top

    wpml_language_form_input_field – Filter the hidden input field rendered by the wpml_add_language_form_field hook.

    availability:
    WPML Version: 3.3.1
    description:

    Filter the hidden input field rendered by the wpml_add_language_form_field hook.

    type:
    filter
    category:
    Site-Wide Language Information
    parameters:
    add_filter( 'wpml_language_form_input_field', callable $function_to_add, 10, 2 );
    $function_to_add
    (callable) (Required) Your callback to be run when the filter is applied.

    There are two parameters being passed to this filter: the language form field and the current language.

    • $language_form_field => The language form field
    • $current_language => The current language

    This filter must return a string of $language_form_field.

    hook example usage:

    Example

    add_filter( 'wpml_language_form_input_field', 'my_filter_function', 10, 2 ); 
    
    function my_filter_function( $language_form_field, $current_language ) {
    	$language_form_field = $language_form_field . sprintf( __( 'The hidden language field lang = %s.', 'text-domain' ), $current_language);
    	return $language_form_field;
    }
    
    // The expected result is like the following line 
    // <input type='hidden' name='lang' value='es' />The hidden language field lang = es.
    do_action( 'wpml_add_language_form_field' );
    
    Back to the top

    wpml_add_language_selector – Display WPML's drop-down language switcher

    availability:
    WPML Version: 3.2
    description:

    Displays the drop down language selector as configured from the “WPML->Languages” admin screen

    type:
    action
    category:
    Site-Wide Language Information
    parameters:
    do_action( 'wpml_add_language_selector' )

    This action hook does not have any parameters.

    hook example usage:

    Add the code below to your theme template files, where you want the language switcher to be displayed at.

    Example

    do_action( 'wpml_add_language_selector' );
    

    If you like you can also add the above code line in a PHP widget like PHP Text Widget

    Back to the top

    wpml_footer_language_selector – Display WPML's horizontal language switcher

    availability:
    WPML Version: 3.2
    description:

    Displays the horizontal footer language selector as configured from the “WPML->Languages” admin screen

    type:
    action
    category:
    Site-Wide Language Information
    parameters:
    do_action( 'wpml_footer_language_selector' )

    This action hook does not have any parameters.

    hook example usage:

    Add the code below to your theme template files, where you want the language switcher to be displayed at.

    Example

    do_action( 'wpml_footer_language_selector' );
    

    If you like you can also add the above code line in a PHP widget like PHP Text Widget

    Back to the top

    wpml_add_language_form_field – Make a custom search form multilingual-ready

    availability:
    WPML Version: 3.2
    description:

    Echoes an HTML hidden input field with name=”lang” and as value the current language.

    In order to add a search form to your theme you would normally use the standard WordPress template tag: get_search_form()
    If you are making use of the default WordPress search form, you do not need to edit anything. WPML will handle the rest.

    However, there may be times when get_search_form() can’t be used. If you are creating a custom search form and you need to make it WPML compatible then this action hook is what you need.

    type:
    action
    category:
    Site-Wide Language Information
    parameters:
    do_action( 'wpml_add_language_form_field' )

    This action hook does not have any parameters.

    hook example usage:

    Add the code below inside your search form code.

    Example

    // Return the HTML code for the current language Spanish
    // <input type='hidden' name='lang' value='es' />
    do_action( 'wpml_add_language_form_field' );
    
    Back to the top

    wpml_element_trid – Get “trid” (the ID of the translation group) of a translated element

    availability:
    WPML Version: 3.3.5
    description:
    • Get trid (the ID of the translation group) of a translated element, which is required for the  wpml_get_element_translations filter and others which expect this argument.
    • Learn more about trid on the WPML’s tables documentation page.
    type:
    filter
    category:
    Site-Wide Language Information
    parameters:
    apply_filters( 'wpml_element_trid', mixed $empty_value, integer $element_id, string $element_type)
    $empty_value
    (mixed) (Required) This is usually the value the filter will be modifying. We are not filtering anything here so set this to NULL. This is needed for the filter function to actually receive the full argument list.
    $element_id
    (integer) (Required) The ID of the item (post_id for post types, term_taxonomy_id for taxonomy terms).
    $element_type
    (string) (Optional) The type of an element. Can be a post type: post_post, post_page, post_attachment, post_nav_menu_item, post_{custom post key} or taxonomy: tax_category, tax_post_tag, tax_nav_menu, tax_{custom taxonomy key}. Defaults to post_post if not set.
    hook example usage:

    Example

    // Get "trid" of the "Sample Page" page. 
    $trid = apply_filters( 'wpml_element_trid', NULL, 2, 'post_page' );
    
    Back to the top

    wpml_get_element_translations – Get the element translations info using “trid” (the ID of the translation group)

    availability:
    WPML Version: 3.3.5
    description:
    • Get the element translations info using trid (the ID of the translation group).
    • trid can be retrieved by the wpml_element_trid filter.
    • Learn more about this on the WPML’s tables documentation page.
    type:
    filter
    category:
    Site-Wide Language Information
    parameters:
    apply_filters( 'wpml_get_element_translations', mixed $empty_value, integer $trid, string $element_type)
    $empty_value
    (mixed) (Required) This is usually the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list.
    $trid
    (integer) (Required) The ID of the translation group.
    $element_type
    (string) (Optional) The type of an element. Can be a post type: post_post, post_page, post_attachment, post_nav_menu_item, post_{custom post key} or taxonomy: tax_category, tax_post_tag, tax_nav_menu, tax_{custom taxonomy key}. Defaults to post_post if not set.
    hook example usage:

    Example

    
    $translations = apply_filters( 'wpml_get_element_translations', NULL, 2, 'post_page' );
    var_dump($translations);
    /**
     * The result looks like the following 
     * 
    array(2) {
      ["en"]=>
      object(stdClass)#1857 (8) {
        ["translation_id"]=>
        string(1) "1"
        ["language_code"]=>
        string(2) "en"
        ["element_id"]=>
        string(1) "2"
        ["source_language_code"]=>
        NULL
        ["element_type"]=>
        string(9) "post_page"
        ["original"]=>
        string(1) "1"
        ["post_title"]=>
        string(4) "Home"
        ["post_status"]=>
        string(7) "publish"
      }
      ["es"]=>
      object(stdClass)#1856 (8) {
        ["translation_id"]=>
        string(3) "141"
        ["language_code"]=>
        string(2) "es"
        ["element_id"]=>
        string(3) "187"
        ["source_language_code"]=>
        string(2) "en"
        ["element_type"]=>
        string(9) "post_page"
        ["original"]=>
        string(1) "0"
        ["post_title"]=>
        string(6) "Inicio"
        ["post_status"]=>
        string(7) "publish"
      }
    }
     */
    
    Back to the top

    wpml_enqueue_browser_redirect_language – Use a custom JavaScript for handling the browser redirection

    availability:
    WPML Version: Comming soon!
    description:

    This filter is used when the theme developer wants to use a custom JavaScript for handling the browser redirection.

    This filters a boolean set to true by default.
    If the filter returns false, the JavaScript which takes care of redirecting the visitor won’t be enqueued.
    The filter is applied only if the wpml_browser_redirect_language_params filter returns a valid $param (pageLanguage and languageUrls must be set).

    type:
    filter
    category:
    Site-Wide Language Information
    parameters:

    pageLanguage – defines a language for the page

    languageUrls – an array that contains pairs of languages and URLs to which browser should be redirected

    hook example usage:

    In order to use this filter Browser language redirect must be enabled on the WPML -> Languages.

    Following code can be used to redirect browser to homepage for a post when language is changed to specific one

    function example_callback( $params ) {
        global $post;
        // Redirect the French language to the home page if the current page ID is 123
        if ( $post->ID === 123 ) {
            $params = array(
                'pageLanguage' => 'en',
                'languageUrls' => array( 'fr' => 'http://example.com/fr/' )
            );
        }
    
        return $params;
    }
    
    add_filter( 'wpml_browser_redirect_language_params', 'example_callback' );
    
    Back to the top

    wpml_default_language – Get the default language enabled for a site

    availability:
    WPML Version: 3.2
    description:

    Returns the default language

    type:
    filter
    category:
    Site-Wide Language Information
    parameters:
    apply_filters( 'wpml_default_language', mixed $empty_value )
    $empty_value
    (mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list

    hook example usage:

    A basic example

    $my_default_lang = apply_filters('wpml_default_language', NULL );
    
    Back to the top

    wpml_language_has_switched – Run actions when switching the global current language in WordPress queries.

    availability:
    WPML Version: 3.2.7
    description:
    • Run your custom functions right after switching the global current language in WordPress queries.
    • To change the current language, use the wpml_switch_language hook.
    type:
    action
    category:
    Site-Wide Language Information
    parameters:
    add_action( 'wpml_language_has_switched', callable $function_to_add );
    $function_to_add
    (callable) (Required) Your callback to be run when the filter is applied.
    hook example usage:

    Example

    function my_plugin_actions() {
      // These actions will be executed right after the global current language has just changed. 
    }
    
    add_action( 'wpml_language_has_switched', 'my_plugin_actions' );
    
    Back to the top

    wpml_enqueued_browser_redirect_language – Run additional logic after WPML has executed the default one or if the value of $params is customized

    availability:
    WPML Version: Comming soon!
    description:

    This hook is executed at the end of the browser redirection PHP logic, after the wpml_browser_redirect_language_params and wpml_enqueue_browser_redirect_language filters. Despite its name, the action is fired even if wpml_enqueue_browser_redirect_language returns true.

    type:
    action
    category:
    Site-Wide Language Information
    parameters:
    $enqueued
    bool If true the script has been enqueued
    $params
    array Data with values, $pageLanguage, $languageUrls and $cookie.

    $pageLanguagestring

    The language of the current page.

    $languageUrlsarray

    Associative array where the key is the language code and the values are the translated URLs of the current page.

    $cookieStores an associative array with the cookie settings. Please refer to Document.cookie for more details. The keys are:

    • name: the name of the cookie (defaults to _icl_visitor_lang_js).
    • domain: the domain in which the cookie must be used (defaults to the current domain and is not meant to be changed).
    • path: the path of the cookie (defaults to /).
    • expiration: the expiration in seconds is read from the value set in Remember visitors’ language preference that can be found in Browser language redirect on the WPML -> Languages.
    hook example usage:
    function override_browser_redirect( $enqueued, $params ) {
        if ( ! $enqueued ) {
            // E.g.: A script which uses IP geolocalization
            wp_enqueue_script( 'my-custom-script', 'url/to/custom.script.js' );
            
            // Pass the `$params` array to the script, so it can use it to find the best match
            wp_localize_script( 'my-custom-script', 'params', $params );
        }
    }
    
    add_action( 'wpml_enqueued_browser_redirect_language', 'override_browser_redirect', 10, 2 );
    
    Back to the top

    wpml_translated_language_name – Get a language's translated name in another language which you specify

    availability:
    WPML Version: 3.2
    description:

    Returns the translated name of a language in another specified language.

    *Note: The languages involved do not need to be active for the site

    type:
    filter
    category:
    Site-Wide Language Information
    parameters:
    apply_filters( 'wpml_translated_language_name', mixed $empty_value, string $lang_code, string $display_code )
    $empty_value
    (mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
    $lang_code
    (string) (Required) The language name will be for this language. Accepts a 2-letter code e.g. en
    $display_code
    (string|bool) (Optional) The language name will display translated in this language. Accepts a 2-letter code e.g. de. If set to false it will return the translated name in the current language. Default is FALSE.
    hook example usage:

    A basic example

    // will return the translation for 'Italian' in Greek
    echo apply_filters( 'wpml_translated_language_name', NULL, 'it', 'el' );
    
    Back to the top

    wpml_language_is_active – Find out if a specific language is enabled for the site

    availability:
    WPML Version: 3.2
    description:

    Returns TRUE or FALSE if a given language has been enabled.

    type:
    filter
    category:
    Site-Wide Language Information
    parameters:
    apply_filters( 'wpml_language_is_active', mixed $empty_value, string $language_code )
    $empty_value
    (mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
    $language_code
    (string) (Required) The language code to check. Accepts a 2-letter code like ‘en’
    hook example usage:

    Example

    // $is_german_enabled will return TRUE if German is enabled and FALSE if not
    $is_german_enabled = apply_filters( 'wpml_language_is_active', NULL, 'de' );
    
    Back to the top

    Retrieving Language Information for Content

    wpml_element_language_code – Get the language code for a translatable element

    availability:
    WPML Version: 3.2.2
    description:

    This filter hook will retrieve the language code for a translatable element by querying WPML’s icl_translations database table.

    Also look at wpml_element_language_details if you are interested in more information such as the element’s trid

    type:
    filter
    category:
    Retrieving Language Information for Content
    parameters:
    apply_filters( 'wpml_element_language_code', string $language_code, array $args )
    $language_code
    (string) (Required) A 2-letter language code. Defaults to null.
    $args
    (array) (Required) An array of arguments to be used.

    • element_id(bool) Use term_taxonomy_id for taxonomies, post_id for posts
    • element_type(string) The type of element to check. Can be a post type: post, page, attachment, nav_menu_item, {custom post key} or taxonomy: category, post_tag, nav_menu {custom taxonomy key}
    hook example usage:

    Example

    $args = array('element_id' => 10, 'element_type' => 'category' );
    $my_category_language_code = apply_filters( 'wpml_element_language_code', null, $args );
    
    Back to the top

    wpml_element_language_details – Get the trid, language code and source language code for a translatable element

    availability:
    WPML Version: 3.2.2
    description:

    This filter hook will retrieve language information for a translatable element. It queries WPML’s icl_translations database table and returns an object with the element’s trid, source language code and language code.

    If you are only looking for the element’s language code you might prefer to use wpml_element_language_code

    type:
    filter
    category:
    Retrieving Language Information for Content
    parameters:
    apply_filters( 'wpml_element_language_details', object $element_object, array $args )
    $element_object
    (object) (Required) A WordPress object. Defaults to null.
    $args
    (array) (Required) An array of arguments to be used.

    • element_id(bool) Use term_taxonomy_id for taxonomies, post_id for posts
    • element_type(string) The type of element to check. Can be a post type: post, page, attachment, nav_menu_item, {custom post key} or taxonomy: category, post_tag, nav_menu {custom taxonomy key}
    hook example usage:

    Example

    $args = array('element_id' => 10, 'element_type' => 'category' );
    $my_category_language_info = apply_filters( 'wpml_element_language_details', null, $args );
    
    Back to the top

    wpml_switch_language – Control language in WordPress queries

    availability:
    WPML Version: 3.2.2
    description:

    This action hook allows controlling the language in WordPress queries. It overrides the WPML language global variable used to filter database query requests.

    Note: The action hook must be passed to the pre_get_posts WordPress hook. Use with caution since it affects the WPML language variable globally. To avoid unexpected results, use the hook in combination with WordPress conditional tags to only alter the specific query on the page you want.

    type:
    action
    category:
    Retrieving Language Information for Content
    parameters:
    do_action( 'wpml_switch_language', string $language_code )
    $language_code
    (string) (Required) The 2-letter language code to switch to. If set to null it restores the original language. If set to ‘all’ it will query content from all active languages. Defaults to null
    hook example usage:

    In the example below, please note the use of conditional tags to control the specific WordPress query we want. For additional information on the use of conditionals please refer to the pre_get_posts page in the WordPress Codex.

    Example

    // using the hook on a custom query on the WordPress index front end page
    function my_custom_something($query) {
        if ( !is_admin() && is_index() && !$query->is_main_query() ) {
            do_action( 'wpml_switch_language', "de" );
        }
    }
    add_action('pre_get_posts', 'my_custom_something');
    
    Back to the top

    wpml_post_language_details – Get the language of a post

    availability:
    WPML Version: 3.2
    description:

    Retrieve language information of a post by its ID.

    The language information that is returned includes:

    • the post language 2-letter code,
    • the post locale,
    • the language text direction (True for RTL, False for LTR),
    • the post language translated name and native name and
    • whether the current language is different to the post language (True/False)
    type:
    filter
    category:
    Retrieving Language Information for Content
    parameters:
    apply_filters( 'wpml_post_language_details', mixed $empty_value, int $post_id )
    $empty_value
    (mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
    $post_id
    (int) (Optional) The post id to retrieve information of (post, page, attachment, custom post) Defaults to current post ID.
    hook example usage:

    In the example below we use the filter to retrieve the language information for the “Hello World” post.
    The original language of the post is English and we have translated it to German.

    Example

    $my_post_language_details = apply_filters( 'wpml_post_language_details', NULL, 1 ) ;
    

    The above will return the following on the English version of the site:

    array (
     'language_code' => 'en',
     'locale' => 'en_US',
     'text_direction' => false,
     'display_name' => 'English',
     'native_name' => 'English',
     'different_language' => false,
    )
    

    If we switch to the German version of the site we will see the following:

    array (
     'language_code' => 'de',
     'locale' => 'de_DE',
     'text_direction' => false,
     'display_name' => 'German',
     'native_name' => 'Deutsch',
     'different_language' => true,
    )
    Back to the top

    Retrieving Localized Content

    wpml_home_url – Get a site's home url for the current language

    availability:
    WPML Version: 3.2
    description:

    Returns the home url in the current language. To be used in place of get_option('home')

    * Note: Good code will make use of get_home_url() or home_url() which apply filters natively. In this case there is no need to replace anything.

    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    apply_filters( 'wpml_home_url', string $home_url )
    $home_url
    (string) (Required) The home url from get_option('home')
    hook example usage:

    Example

    $my_home_url = apply_filters( 'wpml_home_url', get_option( 'home' ) );
    <a href="<?php echo $my_home_url; ?>">Home</a>
    

    The example above will return http://siteurl/ for the default language as we would expect.
    Then when we switch to a secondary language, i.e. German, the url will adjust and display as http://siteurl/de

    Back to the top

    wpml_element_link – Get the url for a post type or taxonomy term for the current language

    availability:
    WPML Version: 3.2
    description:

    Returns a post type link or taxonomy term link in the current language.

    * Note: There are alternative ways to retrieve an element’s link which gives developers fuller control over the HTML output.
    WordPress offers a number of functions to do this such as get_permalink(), get_term_link(), etc.

    If you plan on using functions that require a post type or term ID as a parameter then you may be interested in looking into the wpml_object_id filter.

    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    apply_filters( 'wpml_element_link', int $element_id, string $element_type, string $link_text, array $optional_parameters, string $anchor, bool $echo, bool $return_original_if_missing )
    $element_id
    (int) (Required) The ID of the post type (post, page, attachment, custom post) or taxonomy term (tag, category, custom taxonomy) to link to
    $element_type
    (string) (Optional) The type of element to link to. Can be ‘post’, ‘page’, ‘attachment’, ‘{custom post}’, ‘tag’, ‘category’, ‘{custom taxonomy}’. Defaults to ‘post’
    $link_text
    (string) (Optional) The link text. Defaults to the element’s name
    $optional_parameters
    (array) (Optional) Arguments for the link
    $anchor
    (string) (Optional) Anchor for the link
    $echo
    (bool) (Optional) 0|false to return or 1|true to echo the localized link. Defaults to true
    $return_original_if_missing
    (bool) (Optional) If set to true it will always return a value (the original value, if translation is missing). Default is TRUE
    hook example usage:

    Examples

    //produces: <a href="/hello-world/">Hello World!</a>
    apply_filters( 'wpml_element_link', 1 );
    
    //produces: <a href="/sample-page/">Custom link text for the sample page</a>
    apply_filters( 'wpml_element_link', 2, 'page', __( 'Custom link text for the sample page' ) );
    
    //produces: <a href="/sample-page/?category=foo&bar=baz">Sample Page</a>
    apply_filters( 'wpml_element_link', 2, 'page', '', array( 'category'=>'foo', 'bar'=>'baz' ) );
    
    //produces: <a href="/sample-page/#contact">Sample Page</a>
    apply_filters( 'wpml_element_link', 2, 'page', '', '', 'contact' );
    
    //produces: <a href="/category/uncategorized/">Uncategorized</a>
    apply_filters( 'wpml_element_link', 1, 'category' );
    
    //produces: <a href="/?attachment_id=25">'Attachment image title</a>
    apply_filters( 'wpml_element_link', 25, 'attachment', __( 'Attachment image title' ) );
    
    Back to the top

    wpml_object_id – Get the ID in the current language or in another language you specify

    availability:
    WPML Version: 3.2
    description:

    Returns an element’s ID in the current language or in another specified language.

    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    apply_filters( 'wpml_object_id', int $element_id, string $element_type, bool $return_original_if_missing, mixed $ulanguage_code )
    $element_id
    (int) (Required) The ID of the post type (post, page, attachment, custom post) or taxonomy term (tag, category, custom taxonomy) to filter
    $element_type
    (string) (Required) The type of element the ID belongs to. Can be post, page, {custom post type key}, nav_menu, nav_menu_item, category, post_tag, {custom taxonomy key}
    $return_original_if_missing
    (bool) (Optional) If set to true it will always return a value (the original value, if translation is missing) Default is FALSE
    $ulanguage_code
    (mixed) (Optional) If missing or NULL, it will use the current language. If set to a language code, it will return a translation for that language code or the original if the translation is missing and $return_original_if_missing is set to TRUE. Default is NULL
    hook example usage:

    Some basic examples

    // will return the post ID in the current language for post ID 1
    echo apply_filters( 'wpml_object_id', 1, 'post' );
    
    // will return the category ID in the current language for categoy ID 4. If the translation is missing it will return the original (here: category ID 4)
    echo apply_filters( 'wpml_object_id', 4, 'category', TRUE  );
    
    // will return the German attachment ID for attachment ID 25. If the translation is missing it will return NULL
    echo apply_filters( 'wpml_object_id', 25, 'attachment', FALSE, 'de' );
    

    A more advanced example

    /**
     * Returns the translated object ID(post_type or term) or original if missing
     *
     * @param $object_id integer|string|array The ID/s of the objects to check and return
     * @param $type the object type: post, page, {custom post type name}, nav_menu, nav_menu_item, category, tag etc.
     * @return string or array of object ids
     */
    function my_translate_object_id( $object_id, $type ) {
        $current_language= apply_filters( 'wpml_current_language', NULL );
        // if array
        if( is_array( $object_id ) ){
            $translated_object_ids = array();
            foreach ( $object_id as $id ) {
                $translated_object_ids[] = apply_filters( 'wpml_object_id', $id, $type, true, $current_language );
            }
            return $translated_object_ids;
        }
        // if string
        elseif( is_string( $object_id ) ) {
            // check if we have a comma separated ID string
            $is_comma_separated = strpos( $object_id,"," );
    
            if( $is_comma_separated !== FALSE ) {
                // explode the comma to create an array of IDs
                $object_id     = explode( ',', $object_id );
    
                $translated_object_ids = array();
                foreach ( $object_id as $id ) {
                    $translated_object_ids[] = apply_filters ( 'wpml_object_id', $id, $type, true, $current_language );
                }
    
                // make sure the output is a comma separated string (the same way it came in!)
                return implode ( ',', $translated_object_ids );
            }
            // if we don't find a comma in the string then this is a single ID
            else {
                return apply_filters( 'wpml_object_id', intval( $object_id ), $type, true, $current_language );
            }
        }
        // if int
        else {
            return apply_filters( 'wpml_object_id', $object_id, $type, true, $current_language );
        }
    }
    
    Back to the top

    wpml_translate_string – Retrieve a "package" string translation

    availability:
    WPML Version: 3.2
    description:

    *Retrieves a string translation. The filter looks up a string that is part of a package or a group of strings (as opposed to an individual string**). If it finds it, it looks for a translation in the current language. If a translation exists, it will return it. Otherwise, it will return the original string.

    *To register a “package” string translation please see: wpml_register_string
    **For retrieving an individual text string that does not belong to a package please see: wpml_translate_single_string

    Note: This hook requires the WPML String Translation module

    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    apply_filters( 'wpml_translate_string', string $string_value, string $string_name, (integer|array|object) $package )
    $string_value
    (string) (Required) The string’s original value
    $string_name
    (string) (Required) The string’s registered name
    $package
    (mixed) (Required) The string’s registered package identifier
    • If $package is an array it needs to be associative and contain keys kind and name.
    • If $package is an object it needs to have kind and name fields.
    hook example usage:

    A complete and detailed example can be found on the “String Package Translation” documentation page.

    Back to the top

    wpml_unfiltered_admin_string – Retrieve an option value by-passing WPML ST filters.

    availability:
    WPML Version: 3.2.3-dev
    description:

    WPML String Translation filters theme/plugin setting options in order to return translations of their values in the current language.
    This means that on a WordPress installation with WPML languages set for example to English as primary and German as secondary language, you can expect the German translations to be the values retrieved when calling:get_option('{theme_name}_settings'); while the current language is German. Then while the current language is English, the English values will be displayed.

    This also means however, that when an option value is updated with: update_option('{theme_name}_settings', $new_value); the option value will be updated in both languages. This may not be always desirable.

    This is where the above filter is helpful. The filter allows retrieving an option value by-passing WPML String Translation filters. What is returned is the value in the language it is retrieved in so that further operations taken such as updating it the value in the database will not affect languages other than the one you are working with.

    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    apply_filters( 'wpml_unfiltered_admin_string', mixed $default_value, string $option_name )
    $default_value
    (mixed) (Required) The value to return in case the string does not exist
    $option_name
    (string) (Optional) The name of the option to retrieve. A non SQL-escaped name is expected.
    hook example usage:

    For the example that follows below, imagine you are viewing a language other than the default.
    The option value you are retrieving is saved as a serialized array. You want to update a single key-value pair in the array and save it to the database. You expect that only the current language will be affected.

    Example

    // retrieve option value is current language
    $a = apply_filters( 'wpml_unfiltered_admin_string', get_option( 'my_option_name' ), 'my_option_name' );
    
    // some operations ...
    $a['number']++;
    
    //update the value for the current language only
    update_option('my_option_name', $a); 	
    
    Back to the top

    wpml_get_translated_slug – Get the post type slug translation in a specific language.

    availability:
    WPML Version: 3.2.3
    description:
    • Gets the post type slug translation in a specific language.
    • The translation value is saved in WPML->Translation Management->Multilingual Content Setup->Custom posts.
    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    $translated_slug = apply_filters( 'wpml_get_translated_slug', string $slug, string $post_type, string $language_code );
    $slug
    (string) (Required) The value is set in the rewrite argument of the register_post_type function.
    $post_type
    (string) (Required) The first parameter value of the register_post_type function.
    $language_code
    (string) (Optional) Return the translation in this language. Default is NULL which returns the current language.
    hook example usage:

    Register a book post type with the custom slug my-book.

    In WPML->Translation Management->Multilingual Content Setup->Custom posts, translate the custom slug into Spanish with the value mi-libro.

    Use the wpml_get_translated_slug hook to get the Spanish translation of this custom slug, which is mi-libro.

    The example for wpml_get_translated_slug.
    The example for wpml_get_translated_slug.

    Example

    // Register a "book" post type with the custom slug "my-book"
    add_action( 'init', 'register_book_init' );
    
    function register_book_init() {
    	$labels = array(
    		'name'               => _x( 'Books', 'post type general name', 'your-plugin-textdomain' ),
    		'singular_name'      => _x( 'Book', 'post type singular name', 'your-plugin-textdomain' )
    	);
    
    	$args = array(
    		'labels'             => $labels,
    		'public'             => true,
    		'publicly_queryable' => true,
    		'show_ui'            => true,
    		'show_in_menu'       => true,
    		'rewrite'            => array( 'slug' => 'my-book' ),
    	);
    
    	register_post_type( 'book', $args ); 
    }
    
    // Get the Spanish translation of the post type slug "my-book" 
    // This value is saved in WPML->Translation Management->Multilingual Content Setup->Custom posts
    $translated_slug = apply_filters( 'wpml_get_translated_slug', 'my-book', 'book' ,'es' );
    // Return "mi-libro"
    echo $translated_slug;
    
    Back to the top

    wpml_permalink – Add language information to WordPress permalinks

    availability:
    WPML Version: 3.2.2
    description:

    Filters a WordPress permalink and converts it to a language-specific permalink based on the language URL format set in the WPML language settings.

    This means that when “Language URL format” is set to “Different languages in directories” the permalink will be returned in the http://domain.com/de form. When “A different domain per language” is selected the permalink will be converted to include the correct domain assigned to the requested language.

    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    $permalink
    (string) (Required) The WordPress generated URL to filter.
    $language_code
    (string) (Optional) The language to convert the url into. It accepts a 2-letter code. When set to null, it falls back to default language for root page, or current language in all other cases. Default is null
    $full_resolution
    (boolean) (Optional) Enable full conversion of hard-coded URLs.
    hook example usage:

    Example 1

    For example, if we have “Different languages in directories” selected, we can use the following code:

    // will return http://domain.com/de/contact
    $wpml_permalink = apply_filters( 'wpml_permalink', 'http://domain.com/contact', 'de' );	
    

    Example 2

    We have a page http://example.org/hello/ and its translation http://example.org/fr/bonjour/. Let’s say we are calling the filter while we are displaying the home page http://example.org.

    // displays http://example.org/fr/hello/ (wrong)
    echo apply_filters( 'wpml_permalink', 'http://example.org/hello/', 'fr' ); 
    
    // displays http://example.org/fr/bonjour/ (correct)
    echo apply_filters( 'wpml_permalink', 'http://example.org/hello/', 'fr', true ); 
    

    Important notes about the second example:

    • The full resolution is a heavy process, so WPML has to persist the resolved URLs in the database. The first call to wpml_permalink should significantly increase the database queries and load time. But the subsequent calls should not overload the process.
    • The database persistence is partially cleared when post/terms are updated or deleted. And it’s fully cleared when visiting Settings -> Permalinks (this is a good troubleshooting option in case you encounter any issues).
    • In case the URL could not be resolved, the filter wpml_permalink will return the original URL.
    Back to the top

    wpml_translate_single_string – Retrieve a string translation

    availability:
    WPML Version: 3.2
    description:

    *Retrieves an individual (as opposed to a string that is part of a package**) text string translation. The filter looks for a string with matching $domain and $name. If it finds it, it looks for a translation in the current language or the language you specify. If a translation exists, it will return it. Otherwise, it will return the original string.

    *To register a string for translation please see: wpml_register_single_string
    **For retrieving a string translation that is part of a package please see: wpml_translate_string

    Note: This hook requires the WPML String Translation module

    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    apply_filters( 'wpml_translate_single_string', string $original_value, string $domain, string $name, string $language_code )
    $original_value
    (string) (Required) The string’s original value
    $domain
    (string) (Required) The string’s registered domain
    $name
    (string) (Required) The string’s registered name
    $language_code
    (string) (Optional) Return the translation in this language. Default is NULL which returns the current language
    hook example usage:

    We pick up the same example of the widget we used for the“wpml_register_single_string” action hook. You may want to go there to refresh your memory. We use the “wpml_translate_single_string” filter in the widget’s output function

    Example

    function widget($args, $instance){
            extract($args);
            $title               = apply_filters('widget_title', $instance['title'] );
            $custom_input        = apply_filters('wpml_translate_single_string', $instance['custom_input'], 'Widgets', 'Custom Widget - input field' );
            $custom_textarea     = apply_filters('wpml_translate_single_string', $instance['custom_textarea'], 'Widgets', 'Custom Widget - textarea field' );
    
            # Before the widget
            echo $before_widget;
    
            # The title
            if ( $title )
            echo $before_title . $title . $after_title;
    
            # Output...
    
    Back to the top

    wpml_elements_without_translations – Retrieve untranslated elements

    availability:
    WPML Version: 3.2.2
    description:

    This filter hook can be used to retrieve elements without translations

    type:
    filter
    category:
    Retrieving Localized Content
    parameters:
    apply_filters( 'wpml_elements_without_translations', array $element_ids, array $args )
    $element_ids
    (array) (Required) An array of element ids. Defaults to an empty array.
    $args
    (array) (Required) An array of arguments to be used.

    • target_language(bool) The target language code. A 2-letter code
    • source_language(bool) The source language code. A 2-letter code
    • element_type(string) The type of element to check. Can be a post type: post, page, attachment, nav_menu_item, {custom post key} or taxonomy: category, post_tag, nav_menu {custom taxonomy key}
    hook example usage:

    In the example below we want to find out which blog posts have not yet been translated into Greek.
    Note how as first argument we pass an array of post ids so that if WPML is not active we will get that back.

    Example

    $get_post_args = array( 'posts_per_page' => -1, );
    $posts_array = get_posts( $get_post_args );
    $post_ids = array();
    foreach ( $posts_array as $post ) {
    	$post_ids[] += $post->ID;
    }
    
    $wpml_filter_args = array(
    'element_type' => 'post',
    'source_language' => 'en',
    'target_language' => 'el'
    );
    $posts_without_greek_translations = apply_filters( 'wpml_elements_without_translations', $post_ids, $wpml_filter_args );
    
    Back to the top

    Finding the Translation State of Content

    wpml_element_translation_type – Find out whether a post type or taxonomy term has been translated or duplicated

    availability:
    WPML Version: 3.2
    description:

    Returns a post type or taxonomy term’s translation type (translated or not | duplicated or is a duplicate itself).

    type:
    filter
    category:
    Finding the Translation State of Content
    parameters:
    apply_filters( 'wpml_element_translation_type', mixed $empty_value, int $element_id, string $element_type )
    $empty_value
    (mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
    $element_id
    (int) (Required) The element id to retrieve the information of. Use term_id for taxonomy terms, post_id for post types
    $element_type
    (string) (Required) The type of element the ID belongs to. Can be a post type: post, page, attachment, nav_menu_item, {custom post key} or taxonomy: category, post_tag, nav_menu {custom taxonomy key}
    hook example usage:

    Example

    echo apply_filters( 'wpml_element_translation_type', NULL, 7, 'nav_menu' )
    

    The return value will be one of these:

     *      WPML_ELEMENT_IS_NOT_TRANSLATED  = 0
     *      WPML_ELEMENT_IS_TRANSLATED      = 1
     *      WPML_ELEMENT_IS_DUPLICATED      = 2
     *      WPML_ELEMENT_IS_A_DUPLICATE     = 3
    
    Back to the top

    wpml_element_has_translations – Find out whether a post type or a taxonomy term is translated

    availability:
    WPML Version: 3.2
    description:

    Returns TRUE or FALSE based on whether a post type or taxonomy term is translated or not.

    type:
    filter
    category:
    Finding the Translation State of Content
    parameters:
    apply_filters( 'wpml_element_has_translations', mixed $empty_value, int $element_id, string $element_type )
    $empty_value
    (mixed) (Required) This is normally the value the filter will be modifying. We are not filtering anything here so set this to NULL. This for the filter function to actually receive the full argument list
    $element_id
    (int) (Required) The element id to retrieve the information of. Use term_id for taxonomy terms, post_id for post types
    $element_type
    (string) (Required) The type of element the ID belongs to. Can be a post type: post, page, attachment, nav_menu_item, {custom post key} or taxonomy: category, post_tag, nav_menu {custom taxonomy key}
    hook example usage:

    Example

    //$is_translated will be TRUE if the custom post is translated and FALSE if it is not translated
    $is_translated = apply_filters( 'wpml_element_has_translations', NULL, 61, 'book' )
    
    Back to the top

    wpml_master_post_from_duplicate – Get the original post from its duplicated post

    availability:
    WPML Version: 3.2
    description:

    Returns the original post ID from the duplicated post ID

    type:
    filter
    category:
    Finding the Translation State of Content
    parameters:
    apply_filters( 'wpml_master_post_from_duplicate', int $post_id )
    $post_id
    (int) (Required) The duplicated post id
    hook example usage:

    Example

    // $my_original_post will return the original post ID which was used to create post ID 30
    $my_original_post = apply_filters( 'wpml_master_post_from_duplicate', 30 )
    

    If the above variable returns an empty string this would indicate that post ID 30 is not a duplicated post.

    Back to the top

    wpml_post_duplicates – Get the duplicated posts of another post you specify

    availability:
    WPML Version: 3.2
    description:

    Returns the duplicated post IDs from the original post ID.

    type:
    filter
    category:
    Finding the Translation State of Content
    parameters:
    apply_filters( 'wpml_post_duplicates', int $master_post_id )
    $master_post_id
    (int) (Required) The original post id from which duplicates exist
    hook example usage:

    Example

    // $my_duplications will return an associative array with language codes as indexes and post_ids as values
    $my_duplications = apply_filters( 'wpml_post_duplicates', 28 );
    

    The result looks like this:

    Array
    (
        [de] => 30
        [el] => 73
    )
    

    If I attempt to pass a post ID that has not been used as the original post to create duplicates from the filter will return an empty array. To illustrate this more clearly please compare the example below to the one given above.

    Example

    // note that I use post ID 30 This is the German duplicated post from the first example above
    $my_duplications = apply_filters( 'wpml_post_duplicates', 30 );
    

    And the result:

    Array
    (
    )
    
    Back to the top

    Inserting Content

    wpml_set_element_language_details – Set or update an element's language information

    availability:
    WPML Version: 3.2.7
    description:

    The action hook makes it possible to set or update an element’s language information. Apart from its straightforward implied usage, the hook can prove to be useful when one needs to connect two elements with one as the “Translation of” the other. Refer to the “Hook Example Usage” section below for an example of this.

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_set_element_language_details', array $args )
    $args
    (array) (Required) An array of arguments to be used.

    • element_id(bool) Use term_taxonomy_id for taxonomies, post_id for posts
    • element_type(string) The type of an element. Can be a post type: post_post, post_page, post_attachment, post_nav_menu_item, post_{custom post key} or taxonomy: tax_category, tax_post_tag, tax_nav_menu, tax_{custom taxonomy key}. Defaults to post_post if not set.
    • trid(int) The trid to which the element is to be assigned to. If set to FALSE it will create a new trid for the element causing any potential translation relations to/from it to disappear.
    • language_code(string) The language code for the element
    • source_language_code(string) The source language code for the element. NULL is reserved for original elements i.e. elements that are not a translation of another. Defaults to NULL when not set.
    • check_duplicates(bool) Defaults to TRUE. What this does is, it checks whether another element of a different type with the same ID already exists and outputs a user-level notice (E_USER_NOTICE) with the message “Element ID already exists with a different type”
    hook example usage:
    In the example below, we use the my_insert_posts() function to insert two posts from the front-end. One original and one translation.
    This function is called in element_connect_on_insert(). This is our main function which will connect the two posts together.Note the use of two other useful WPML hooks inside. The wpml_element_type filter for filtering the element type to a value WPML will understand and the wpml_element_language_details filter for retrieving the original trid and language code.All of this hooks on wp_footer so our filters and actions will fire when the footer is loaded on the front-end.

    Example

    add_action('wp_footer', 'element_connect_on_insert');
    
    function my_insert_posts() {
    	$output = array();
    
    	// Create original post object
    	$my_original_post = array(
    		'post_title'    => 'My original post',
    		'post_content'  => 'This is my original post.',
    		'post_status'   => 'publish',
    		'post_author'   => 1,
    		'post_category' => array(1)
    	);
    
    	// Create translation post object
    	$my_translated_post = array(
    		'post_title'    => 'My translated post',
    		'post_content'  => 'This is my translated post.',
    		'post_status'   => 'publish',
    		'post_author'   => 1,
    		'post_category' => array(2) // NOTE: this is the translated category id!
    	);
    
    	// Insert the 2 posts into the database
    	$original_post_id = wp_insert_post( $my_original_post );
    	$translated_post_id = wp_insert_post( $my_translated_post );
    
    	return $output = array(
    		'original' => $original_post_id,
    		'translation' => $translated_post_id
    	);
    }
    
    
    function element_connect_on_insert() {
    	$inserted_post_ids = my_insert_posts();
    
    	if ( $inserted_post_ids) {
    		// https://wpml.org/wpml-hook/wpml_element_type/
    		$wpml_element_type = apply_filters( 'wpml_element_type', 'post' );
    		
    		// get the language info of the original post
    		// https://wpml.org/wpml-hook/wpml_element_language_details/
    		$get_language_args = array('element_id' => $inserted_post_ids['original'], 'element_type' => 'post' );
    		$original_post_language_info = apply_filters( 'wpml_element_language_details', null, $get_language_args );
    		
    		$set_language_args = array(
    			'element_id'    => $inserted_post_ids['translation'],
    			'element_type'  => $wpml_element_type,
    			'trid'   => $original_post_language_info->trid,
    			'language_code'   => 'de',
    			'source_language_code' => $original_post_language_info->language_code
    		);
    
    		do_action( 'wpml_set_element_language_details', $set_language_args );
    	}
    }
    
    Back to the top

    wpml_show_package_language_ui – Display a language information box in the admin UI for content

    availability:
    WPML Version: 3.2
    description:

    Outputs the UI to display a language information box in admin screens of content that was registered for translation as a string package*. It also shows the current state of any translations.

    *String translation packages are registered with wpml_register_string and their translations retrieved with wpml_translate_string

    Note: This hook requires the WPML String Translation module

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_show_package_language_ui', array $package, array $args )
    $package
    (array) (Required) The package object. Array keys must match the following WPML_Package fields and will be the same for all texts sent to translation for an object:

    • kindA free text to identify the package object. Must be the same for all packages of the same type. i.e. ‘Gravity Form’ or ‘Layout’
    • nameA name to identify the set of strings with. Must be unique for each package of the same type such as an ID
    • titleA humanly readable title for the package. Must be different for each package of the same type.
    • edit_linkLink to edit this set of strings (it can be an empty string)
    • view_linkLink to view this set of strings (it can be an empty string)
    $args
    (array) (Optional) Arguments to control the output

    • $show_title(bool) Will hide/show the “WPML Translation” title in the box. Defaults to TRUE
    • $show_description(bool) Will hide/show the “Language of this {package_kind} is {language_name}” Defaults to TRUE
    • $show_status(bool) Will hide/show the translation status” Defaults to TRUE
    • $show_link(bool) Will hide/show the link which leads to the translation dashboard. Defaults to TRUE
    • $title_tag(string) The HTML Tag to use for the box title. Defaults to ‘h2’
    • $status_container_tag(string) The HTML Tag to use for translation status container. Defaults to ‘p’
    • $main_container_attributes(array) Array of keys->values to add to the main container (for CSS and/or js) Defaults to an empty array
    • $status_container_attributes(array) Array of keys->values to add to the status container (for CSS and/or js) Defaults to array( 'style' => 'padding-left: 10px' )
    hook example usage:

    Simple Example using Layouts

    $package = array(
            'kind' => 'Layout',
            'name' => 'contact-us');
    
    do_action('wpml_show_package_language_ui', $package);
    
    Back to the top

    wpml_make_post_duplicates – Create duplicate posts programatically

    availability:
    WPML Version: 3.2
    description:

    Builds duplicate posts from a “master” post. This action hook is reserved for front-end calls.

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_make_post_duplicates', int $master_post_id )
    $master_post_id
    (int) (Required) The ID of the post to duplicate from. It can be that of a post, page or custom post. The “master post” doesn’t need to be in the default language
    hook example usage:

    In the example below, we create duplicates for a post when we insert it from the front-end.
    Our function will fire when the footer is loaded on the front-end.

    Example

    add_action('wp_footer', 'my_duplicate_on_insert');
    function my_duplicate_on_insert() {
    	// Create post object
    	$my_post = array(
    	  'post_title'    => 'My post to insert from the front-end',
    	  'post_content'  => 'This is my post.',
    	  'post_status'   => 'publish',
    	  'post_author'   => 1,
    	  'post_category' => array(1)
    	);
    
    	// Insert the post into the database
    	$post_id = wp_insert_post( $my_post );
    	if ( $post_id ) {
    		do_action( 'wpml_make_post_duplicates', $post_id );
    	}
    }
    
    Back to the top

    wpml_register_string – Register dynamic texts for translation

    availability:
    WPML Version: 3.2
    description:

    *Registers a text string for translation. The string being registered is part of a package or a group of strings (as opposed to an individual string**).

    *For retrieving a “package” string translation please see: wpml_translate_string
    **For registering an individual text string that does not belong to a package please see: wpml_register_single_string

    Note: This hook requires the WPML String Translation module

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_register_string', string $string_value, string $string_name, array $package, string $string_title, string $string_type )
    $string_value
    (string) (Required) The string to register for translation
    $string_name
    (string) (Required) A unique name for the string
    $package
    (array) (Required) The package object. Array keys must match the following WPML_Package fields and will be the same for all texts sent to translation for an object:

    • kind A free text to identify the package object. Must be the same for all packages of the same type. i.e. ‘Gravity Form’ or ‘Layout’
    • name A name to identify the set of strings with. Must be unique for each package of the same type such as an ID.
    • title A humanly readable title for the package. Must be different for each package of the same type.
    • edit_link Link to edit this set of strings (it can be an empty string)
    • view_link Link to view this set of strings (it can be an empty string)
    $string_title
    (string) (Required) A title for the string (together with $string_name it will be used to build the name field in icl_strings table)
    $string_type
    (string) (Required) The string kind. Must be one of the following values:

    • AREA Anything that must contain multiple rows
    • LINE A single line value
    • VISUAL This will be shown as a WYSIWYG editor and will be handled as HTML content
    hook example usage:

    A complete and detailed example can be found on the “String Package Translation” documentation page.

    Back to the top

    wpml_register_string_packages – Register in bulk dynamic texts for translation

    availability:
    WPML Version: 3.2
    description:

    Registers string packages for translation. It allows for strings to registered in bulk* if the package translation plugin is activated after content has been created.

    *String packages would otherwise be registered with wpml_register_string and their translations retrieved with wpml_translate_string

    Note: This hook requires the WPML String Translation module

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_register_string_packages', string $type, array $existing )
    $type
    (string) (Required) The type of package to register. This matches the ‘kind’ array key in the $packages parameter as documented for wpml_register_string
    $existing
    (array) (Required) An array of existing package names. Use this so that existing packages are not re-registered. This matches the ‘name’ array key in the $packages parameter as documented for wpml_register_string
    hook example usage:

    Example using Layouts

    add_action('wpml_register_string_packages', 'register_all_for_translation', 10, 2);
    function register_all_for_translation($type, $existing) {
       global $wpdb;
    
       if ($type == 'layout') {
       	$layouts = $wpdb->get_col("SELECT ID FROM {$wpdb->posts} WHERE post_type = 'dd_layouts' AND post_status = 'publish'");
       	foreach ($layouts as $layout_id) {
       		if (!in_array($layout_id, $existing)) {
                         // register the strings in this layout for translation
       			$this->register_strings_for_translation($layout_id);
       		}
       	}
       }
    }
    
    Back to the top

    wpml_multilingual_options – Enable the possibility to save theme/plugin options per language.

    availability:
    WPML Version: 3.9.3
    description:

    Enables the possibility to save a different value per language for your theme/plugin options using WPML language switcher on directly the settings screen.

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_multilingual_options', $wp_option_name );
    

    $wp_option_name

    (Required) Exact option name as it is stored in wp_options table database.

    hook example usage:

    Let’s say that you need to assign a different value per language (translate) for a theme option, this usually is easily achievable with the help of WPML String Translation.

    However, you may need to act differently with some themes and add a different value directly from the theme options panel. For example, with Avada you can do.

    Now, you are working with a theme where you need to translate your options with this later approach, for example your footer option theme_footer. For this, you would need to:

    • Add a value for your footer option at Theme Options > Footer,
    • Add the following code on your functions.php file and queue it as early as possible:
      add_action( 'init', 'my_theme_bootstrap' );
      
      function my_theme_bootstrap(){
         do_action( 'wpml_multilingual_options', 'theme_footer' );
         $settings = get_option( 'theme_footer');
         // [...]
      }
    • Go back to your Theme Options > Footer.
    • Click on the language switcher placed on the top bar and switch languages.
    • Add a new different value for it.
    • You should keep a different value per language.
    • If you visit the front-end, it should display a different value for the option.
    • If you check the database, there should be a new value stored in wp_options table as theme_footer_fr, where _fr is the language suffix.
    Back to the top

    wpml_register_single_string – Register user input texts for translation

    availability:
    WPML Version: 3.2
    description:

    *Registers a individual (as opposed to a string that is part of a package**) text string for translation. This action is usually used for user input texts otherwise referred to as “dynamic text strings”

    *For retrieving a string translation please see: wpml_translate_single_string
    **For registering a text string that is part of a package please see: wpml_register_string

    Note: This hook requires the WPML String Translation module

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_register_single_string', string $context, string $name, string $value )
    $context
    (string) (Required) This value gives the string you are about a context. This will usually be the name of the plugin or theme, in a human readable format
    $name
    (string) (Required) The name of the string which helps the translator understand what’s being translated
    $value
    (string) (Required) The string that needs to be translated
    hook example usage:

    Imagine you have created a custom widget with a title input field and some other options. You can register the widget title for translation using apply_filters but you also want to register the input text you can save in the widget’s other option fields.

    Registering input texts for translation is best done when the widget options are saved or updated i.e. inside the ‘update’ method of widgets.

    Below is an example of what the code could look like. Our example custom widget has a title, a single line input field and a text area.

    Example

    function update($new_instance, $old_instance){
    	$instance = $old_instance;
    	$instance['title'] 		= strip_tags($new_instance['title']);
    	$instance['custom_input'] 	= strip_tags($new_instance['custom_input']);
    	$instance['custom_textarea'] 	= $new_instance['custom_textarea'];
    
    	//WMPL
    	/**
    	 * register strings for translation
    	 */
    	do_action( 'wpml_register_single_string', 'Widgets', 'Custom Widget - input field', $instance['custom_input'] );
    	do_action( 'wpml_register_single_string', 'Widgets', 'Custom Widget - textarea field', $instance['custom_textarea'] );
    	//WMPL
    
    	return $instance;
    }
    

    The code above tells WPML that the user input text for the input field and textarea needs to be translated. The texts will be registered under the “Widgets” strings context with the name “Custom Widget – input field” and “Custom Widget – textarea field” respectively.

    Back to the top

    wpml_delete_package_action – Deletes a string translation package

    availability:
    WPML Version: 3.2
    description:

    Deletes a string translation package*. When this action is called, all the data related to the package is deleted: package, strings, strings translations and jobs.

    *String translation packages are registered with wpml_register_string and their translations retrieved with wpml_translate_string

    Note: This hook requires the WPML String Translation module

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_delete_package_action', string $package_name, string $package_kind )
    $package_name
    (string) (Required) The unique name of the package as it was registered with wpml_register_string
    $package_kind
    (string) (Required) The package kind as used when it was registered using wpml_register_string
    hook example usage:

    Example using Layouts

    add_action( 'before_delete_post', 'my_deleted_post' );
    function my_deleted_post( $post_id ) {
        $is_a_layout_delete_action = isset( $_POST[ 'action' ] ) && $_POST[ 'action' ] == 'delete_layout_record';
        $layout_ids_to_delete = isset( $_POST[ 'layout_id' ] ) ? (array)$_POST[ 'layout_id' ] : array();
    
        if ( $is_a_layout_delete_action && in_array($post_id, $layout_ids_to_delete) ) {
            $package_name = $post_id;
            $package_kind = 'layout';
            do_action( 'wpml_delete_package_action', $package_name, $package_kind );
        }
    }
    
    Back to the top

    wpml_admin_make_post_duplicates – Create or update duplicate posts programatically

    availability:
    WPML Version: 3.2
    description:

    Builds or updates duplicate posts from a “master” post. This action hook is reserved for admin backend calls.

    type:
    action
    category:
    Inserting Content
    parameters:
    do_action( 'wpml_admin_make_post_duplicates', int $master_post_id )
    $master_post_id
    (int) (Required) The ID of the post to duplicate from. It can be that of a post, page or custom post. The “master post” doesn’t need to be in the default language.
    hook example usage:

    Example

    // this will create duplicates for the "Hello World!" post
    do_action( 'wpml_admin_make_post_duplicates', 1 );
    

    In the example below, we create duplicates for a post or page or custom post when we click on “publish” from the “edit-post” admin screen.

    A more advanced example

    add_action( 'wp_insert_post', 'my_duplicate_on_publish' );
    function my_duplicate_on_publish( $post_id ) {
    	global $post;
    	// don't save for autosave
    	if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
    		return $post_id;
    	}
    	// dont save for revisions
    	if ( isset( $post->post_type ) && $post->post_type == 'revision' ) {
    		return $post_id;
    	}
    
    	// we need this to avoid recursion see add_action at the end
    	remove_action( 'wp_insert_post', 'my_duplicate_on_publish' );
    
    		// make duplicates if the post being saved
    		// #1. itself is not a duplicate of another or
    		// #2. does not already have translations
    
    		$is_translated = apply_filters( 'wpml_element_has_translations', '', $post_id, $post->post_type );
    
    		if ( !$is_translated ) {
    			do_action( 'wpml_admin_make_post_duplicates', $post_id );
    		}
    
    	// must hook again - see remove_action further up
    	add_action( 'wp_insert_post', 'my_duplicate_on_publish' );
    }
    
    Back to the top

    Miscellaneous

    wpml_tf_feedback_open_link – Display WPML's translation feedback link

    availability:
    WPML Version: 3.8
    description:

    Display the front-end link to the WPML Translation Feedback feature. Clicking this link displays the dialog box for users to leave their feedback about the current page’s translation.

    type:
    action
    category:
    Miscellaneous
    parameters:
    do_action( 'wpml_tf_feedback_open_link', $args );
    $args
    (array) (Optional) Arguments to filter the translation feedback link output:

    • title – Link text to display on the front-end.
    • classes  classes to add to the <a> tag.
    hook example usage:

    Add the code below to your theme’s footer.php template file or where you want the translation feedback link to be displayed at. The link in this example would be underlined and red.

    Example

    
    <style>
        .my-custom-rate-link {
            text-decoration: underline;
            color: red;
        }
    </style>
    
    <?php $args = array( 'title' => __( 'Please rate the page', 'my-text-domain' ),
        'classes' => 'my-custom-rate-link',
    );
    do_action( 'wpml_tf_feedback_open_link', $args );
    ?>
    
    Back to the top

    wpml_ls_directories_to_scan – Add directories containing language switcher templates

    availability:
    WPML Version: 3.6.0
    description:
    • Add directories containing language switcher templates.
    • This hook is useful when developers want to add their own directories instead of the default directory {your-theme-folder}/wpml/templates/language-switchers/.
    • See more at the Designing Custom Language Switchers Using Template Files document.
    type:
    filter
    category:
    Miscellaneous
    parameters:
    add_filter( 'wpml_ls_directories_to_scan', 'the_callback_function' );

    There is only one parameter passed to this filter: dirs.

    $dirs
    (array) The array including directories.
    hook example usage:

    Example

    function wpmlhook_ls_dirs_to_scan( $dirs ) {
    
        $dirs[] = __DIR__ . '/templates/';
    
        return $dirs;
    }
    add_filter( 'wpml_ls_directories_to_scan', 'wpmlhook_ls_dirs_to_scan' );
    
    Back to the top

    wpml_ls_model_css_classes – Filter CSS classes for language switcher wrappers. These wrappers are not available for language switchers in menus.

    availability:
    WPML Version: 3.6.0
    description:

    Filter CSS classes for language switcher wrappers. These wrappers are not available for language switchers in menus.

    type:
    filter
    category:
    Miscellaneous
    parameters:
    add_filter( 'wpml_ls_model_css_classes', 'the_callback_function' );

    There is only one parameter passed to this filter: css_classes.

    $css_classes
    (array) The array including CSS classes for language switcher wrappers.
    hook example usage:

    Example

    function wpmlhook_ls_model_css_classes( $css_classes ) {
    
        $css_classes[] = 'wpmlhook_custom';
    
        return $css_classes;
    }
    add_filter( 'wpml_ls_model_css_classes', 'wpmlhook_ls_model_css_classes' );
    
    Back to the top

    wpml_ls_model_language_css_classes – Filter CSS classes for each item in a language switcher

    availability:
    WPML Version: 3.6.0
    description:

    Filter CSS classes for each item in a language switcher.

    type:
    filter
    category:
    Miscellaneous
    parameters:
    add_filter( 'wpml_ls_model_language_css_classes', 'the_callback_function' );

    There is only one parameter passed to this filter: css_classes.

    $css_classes
    (array) The array including CSS classes for each item of language switchers.
    hook example usage:

    Example

    function wpmlhook_ls_model_language_css_classes( $css_classes ) {
    
        $css_classes[] = 'wpmlhook_custom';
    
        return $css_classes;
    }
    add_filter( 'wpml_ls_model_language_css_classes', 'wpmlhook_ls_model_language_css_classes' );
    
    Back to the top

    wpml_st_loaded – Run actions after WPML String Translation is fully configured and loaded.

    availability:
    WPML Version: 3.2.1
    description:
    • To make sure a WPML String Translation dependent code is executed at the right time, this code should be hooked into the wpml_st_loaded action. This action is called after WPML String Translation is fully configured and loaded.
    • If we do not hook into this wpml_st_loaded, sometimes the WPML String Translation dependent code might be called too early. Then even if WPML String Translation is active and configured, we may not get expected results.
    • wpml_st_loaded is executed during the plugins_loaded and wpml_loaded actions.
    • There is a similar hook for WPML Translation Management wpml_tm_loaded.
    type:
    action
    category:
    Miscellaneous
    parameters:
    add_action( 'wpml_st_loaded', callable $function_to_add );
    $function_to_add
    (callable) (Required) Your callback to be run when the filter is applied.
    hook example usage:

    Example

    function my_plugin_wpml_st_code() {
      // Run WPML String Translation dependent actions
      // These actions will be executed right after WPML String Translation is fully configured and loaded.
    }
    
    add_action( 'wpml_st_loaded', 'my_plugin_wpml_st_code' );
    
    Back to the top

    wpml_tm_loaded – Run actions after WPML Translation Management is fully configured and loaded.

    availability:
    WPML Version: 3.2.1
    description:
    • To make sure a WPML Translation Management dependent code is executed at the right time, this code should be hooked into the wpml_tm_loaded action. This action is called after WPML Translation Management is fully configured and loaded.
    • If we do not hook into this wpml_tm_loaded, sometimes the WPML Translation Management dependent code might be called too early. Then even if WPML Translation Management is active and configured, we may not get expected results.
    • wpml_tm_loaded is executed during the plugins_loaded and wpml_loaded actions.
    • There is a similar hook for WPML Translation Management wpml_st_loaded.
    type:
    action
    category:
    Miscellaneous
    parameters:
    add_action( 'wpml_tm_loaded', callable $function_to_add );
    $function_to_add
    (callable) (Required) Your callback to be run when the filter is applied.
    hook example usage:

    Example

    function my_plugin_wpml_tm_code() {
      // Run WPML Translation Management dependent actions
      // These actions will be executed right after WPML Translation Management is fully configured and loaded.
    }
    
    add_action( 'wpml_tm_loaded', 'my_plugin_wpml_tm_code' );
    
    Back to the top

    wpml_editor_cf_to_display – Filter custom fields displayed in WPML's translation editor

    availability:
    WPML Version: 3.2
    description:

    WPML applies this hook filter on custom field values when a post is displayed in translation editor. The custom field value is in this way made available to external themes and plugins for filtering.

    Note: This hook requires the WPML Translation Management module

    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_editor_cf_to_display', object $element, object $job )
    $element
    (object) (Optional) The element object available for filtering
    $job
    (object) (Optional) The job object the $element belongs to
    hook example usage:

    A basic example

    add_filter('wpml_editor_cf_to_display', 'callback_1', 10, 2);
    
    function callback_1($element, $job) {
    
      // some super code which DECODES encoded values in $element
      // eg:
      $element->field_data = base64_decode($element->field_data);
    
      return $element;
    
    }
    
    Back to the top

    wpml_tm_save_translation_cf – Filter custom fields before saving in WPML's translation editor or XLIFF import

    availability:
    WPML Version: 3.2
    description:

    WPML applies this hook filter on custom field values when a translation is saved either via the translation editor screen or via an XLIFF import. The custom field value is in this way made available to external themes and plugins for further manipulation before saving e.g. encoding or substitution.

    Note: This hook requires the WPML Translation Management module

    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_tm_save_translation_cf', array $field, string $fieldname, array $data )
    $field
    (array) (Optional) The current custom field array
    $fieldname
    (string) (Optional) The custom field name
    $data
    (array) (Optional) The data array being processed through the filter
    hook example usage:

    A basic example

    add_filter('wpml_tm_save_translation_cf', 'callback_2', 10, 3);
    
    function callback_2($field, $fieldname, $data) {
    
      // some super code which ENCODES values in $field
      // eg
      $field['data'] = base64_encode($field['data']);
    
      return $field;
    }
    
    Back to the top

    wpml_hide_management_column – Allow hiding the translation management column based on post types.

    availability:
    WPML Version: 3.4.1
    description:
    • Allows hiding the translation management column based on the post type.
    • This filter is working in sync with Screen Options. Therefore, hiding column from Screen Options will have the same effect.
    type:
    filter
    category:
    Miscellaneous
    parameters:
    add_action( 'wpml_hide_management_column', 'the_callback_function', 10, 2 );

    There are two parameters being passed to this action:

    $is_visible
    (bool) Whether or not the translation management column displays.
    $post_type
    (string) The post type.

    This filter must return a bool value of $is_visible.

    hook example usage:

    Example

    add_filter( 'wpml_hide_management_column', array( $this, 'my_filter_function' ), 10, 2 );
    
    /**
     * Hide management column by default for products.
     *
     */
    function my_filter_function( $is_visible, $post_type ) {
    	if ( 'product' === $post_type ) {
    		$is_visible = false;
    	}
    
    	return $is_visible;
    }
    
    Back to the top

    wpml_tm_xliff_export_translated_cf – Filter translated custom field values before XLIFF export

    availability:
    WPML Version: 3.2
    description:

    WPML applies this hook filter to the translated custom field values when a document is exported to an XLIFF file. The custom field value is in this way made available to external themes and plugins for further manipulation before saving e.g. substitution.

    Note: This hook requires the WPML Translation Management module

    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_tm_xliff_export_translated_cf', string $field_data_translated, object $element )
    $field_data_translated
    (string) (Optional) The encoded translated custom field value. Empty if not translated yet
    $element
    (object) (Optional) The current custom field
    hook example usage:

    A basic example

    add_filter( 'wpml_tm_xliff_export_translated_cf', 'callback_3', 10, 2 );
    
    function callback_3( $field_data_translated, $element ) {
      $field_data_translated = base64_decode( $field_data_translated );
    
      return $field_data_translated;
    }
    
    Back to the top

    wpml_tm_xliff_export_original_cf – Filter original custom field values before XLIFF export

    availability:
    WPML Version: 3.2
    description:

    WPML applies this hook filter to the original custom field values when a document is exported to an XLIFF file. The custom field value is in this way made available to external themes and plugins for further manipulation before saving e.g. substitution.

    Note: This hook requires the WPML Translation Management module

    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_tm_xliff_export_original_cf', string $field_data, object $element )
    $field_data
    (string) (Optional) The encoded original custom field value.
    $element
    (object) (Optional) The current custom field
    hook example usage:

    A basic example

    add_filter('wpml_tm_xliff_export_original_cf', 'callback_3', 10, 2);
    
    function callback_3( $field_data, $element ) {
      $field_data = base64_decode( $field_data );
    
      return $field_data;
    }
    
    Back to the top

    wpml_sync_custom_field – Sync custom field value across all translations of a given post

    availability:
    WPML Version: 3.9.1
    description:

    Synchronizes the value of a specified custom field across all translations of a given post. It only does it if the translation option for this custom field is set to Copy.

    type:
    action
    category:
    Miscellaneous
    parameters:
    do_action( 'wpml_sync_custom_field', $post_id, $custom_field );

    For this action hook, you only need to provide a post ID and the slug of the custom field you want to synchronize.

    hook example usage:
    do_action( 'wpml_sync_custom_field', 1234, $event-date );
    Back to the top

    wpml_duplicate_generic_string – Filter post data upon duplication before saving

    availability:
    WPML Version: 3.2
    description:

    WPML applies this hook filter on custom field values, post content, post title and post excerpt when a WordPress post type is being duplicated and before the data is saved into the database. The data are in this way made available to external themes and plugins for filtering.

    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_duplicate_generic_string', string $value_to_filter, string $target_language, array $meta_data )
    $value_to_filter
    (string) (Required) The data string to filter
    $target_language
    (string) (Optional) The target language code
    $meta_data
    (array) (Optional) See details below:

    • context(string) The data context. Set to “custom_field” if the value belongs to a custom field and “post” for all other cases (post title, content or excerpt)
    • attribute(string) Set to: “value” for custom fields, “content” for post content, “title” for post title, “excerpt” for post excerpt
    • key(string) The $post_meta->meta_key if the filter is being applied to custom field values. Otherwise the id of the original post that acts as master for duplication
    • $is_serialized(bool) Passed only for custom field data. true|false Whether the data is serialized. This allows to unserialize the value if needed.
    • post_id(int) Passed only for custom field data. The id of the post being duplicated
    • master_post_id(int) Passed only for custom field data. The id of the original post that acts as master for duplication
    hook example usage:

    A basic example

    function my_override_post_duplication( $value_to_filter, $target_language, $meta_data ) {
        $context = $meta_data[ 'context' ];
        if ( $value_to_filter !== '' && $context ) {
            $prefix = '';
    
            $attribute = $meta_data[ 'attribute' ];
            if ( $context == 'post' ) {
                switch ( $attribute ) {
                    case 'content':
                        $prefix = '<h3>' . $target_language . '</h3>';
                        break;
                    case 'excerpt':
                        $prefix = $target_language . "nn";
                        break;
                    default:
                        $prefix = '[' . $target_language . '] ';
                }
            } elseif ( $context == 'custom_field' && $attribute == 'value' ) {
                $is_serialized = $meta_data[ 'is_serialized' ];
                if ( ! $is_serialized && is_string( $value_to_filter ) && ! is_numeric( $value_to_filter ) ) {
                    $prefix = '[' . $target_language . '] ';
                }
            }
    
            if($prefix) {
                $value_to_filter = $prefix . $value_to_filter;
            }
        }
    
        return $value_to_filter;
    }
    
    add_filter( 'wpml_duplicate_generic_string', 'my_override_post_duplication', 10, 3 );
    
    Back to the top

    wpml_element_type – Get the WPML element type name for a post type or taxonomy term as saved in the database

    availability:
    WPML Version: 3.2
    description:

    Filters a WordPress element type (post type, taxonomy term, comment) by adding the WPML prefix ‘post_’, ‘tax_’ (for default tags use ‘post_tag’), or nothing for ‘comment’ as used in the icl_translations db table.

    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_element_type', string $element_type )
    $element_type
    (string) (Required) Accepts comment, post, page, attachment, nav_menu_item, {custom post key}, nav_menu, category, post_tag, {custom taxonomy key}
    hook example usage:

    Example

    //$wpml_element_type will return 'post_attachment'
    $wpml_element_type = apply_filters( 'wpml_element_type', 'attachment' );
    
    Back to the top

    wpml_is_redirected – Disable WPML canonical URL redirection

    availability:
    WPML Version: 4.0.0
    description:

    WPML automatically tries to redirect visitors to the canonical URL when it does find a match. This hook allows to disable this WPML functionality.

    type:
    filter
    category:
    Miscellaneous
    parameters:
    add_filter( 'wpml_is_redirected', 'callable $function_to_add, 10, 3 );

    There are three parameters being passed to this filter:

    $redirect
    (bool) Boolean value to define whether or not to disable WPML canonical URL redirection actions.
    $post_id
    (integer) post ID
    $query
    (array) The WordPress query array.
    hook example usage:

    The following example prevents WPML canonical URL redirection for a Custom Post Type with a slug of “city”

    function mytheme_do_not_redirect_city_post_type( $redirect, $post_id, $query ) {
        if ( 'city' === $query->get( 'post_type' ) ) {
           return false;
         }
        return $redirect;
        };
    add_filter( 'wpml_is_redirected', 'mytheme_do_not_redirect_city_post_type', 10, 3 );
    
    Back to the top

    wpml_cross_domain_language_data – Pass data among language domains.

    availability:
    WPML Version: 3.2.7
    description:
    type:
    filter
    category:
    Miscellaneous
    parameters:
    add_filter( 'wpml_cross_domain_language_data', callable $function_to_add);
    $function_to_add
    (callable) (Required) Your callback to be run when the filter is applied.
    hook example usage:

    We use wpml_cross_domain_language_data to pass the cookie data. In other domains, we use wpml_get_cross_domain_language_data to handle the data and save the cookie.

    Example

    add_filter( 'wpml_cross_domain_language_data', 'pass_data_to_domain' ); // after plugins loaded
    
    // this will be executed on the original domain where we have access to the cookie
    function pass_data_to_domain( $xdomain_data ) {
    	if ( isset ( $_COOKIE[ 'cookie_name' ] ) ) {
    		$xdomain_data[ 'cookie_name' ] = $_COOKIE[ 'cookie_name' ];
    	}
       return $xdomain_data;
    }
    
    add_action( 'init', 'set_xdomain_data_cookie' );
    
    // this handle the xdomain_data and set the cookie
    function set_xdomain_data_cookie() {
    	$xdomain_data = apply_filters( 'wpml_get_cross_domain_language_data', array() );
    	if ( isset ( $xdomain_data[ 'cookie_name' ] ) ) {
    		setcookie( 'cookie_name', $xdomain_data[ 'cookie_name' ], time() + 30 * DAY_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN );
    	}
    }
    
    Back to the top

    wpml_sync_all_custom_fields – Sync values of all custom fields across all translations of a given post

    availability:
    WPML Version: 3.9.1
    description:

    Synchronizes the values of all custom fields across all translations of a given post. It only does it if the translation option for these custom fields are set to Copy.

    type:
    action
    category:
    Miscellaneous
    parameters:
    do_action( 'wpml_sync_all_custom_fields', $post_id );

    For this action hook, you only need to provide an ID of a post for which you want to synchronize custom fields.

    hook example usage:
    do_action( 'wpml_sync_all_custom_fields', 1234)
    Back to the top

    wpml_translatable_user_meta_fields – Make certain user meta fields translatable through WPML String Translation.

    availability:
    WPML Version: 3.3.7
    description:

    Filters an array of user meta keys which will be translated when calling the function get_the_author(). The translatable user meta fields will be registered as strings in WPML String Translation.

    type:
    filter
    category:
    Miscellaneous
    parameters:
    add_filter( 'wpml_translatable_user_meta_fields', array $user_meta_fields );
    $user_meta_fields
    (array) (Required) Containing the user meta fields to translate.
    hook example usage:

    Example

    function add_favorite_food_user_field( $user_meta_fields ) {
        $user_meta_fields[] = 'favorite_food';
        return $user_meta_fields;
    }
    add_filter( 'wpml_translatable_user_meta_fields', 'add_favorite_food_user_field' );
    
    Back to the top

    wpml_get_cross_domain_language_data – Retrieve the data passed among language domains.

    availability:
    WPML Version: 3.2.7
    description:
    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_get_cross_domain_language_data', array $array );
    $array
    (array) (Required) This is just an empty array, you should always use this value array().
    hook example usage:

    We use wpml_cross_domain_language_data to pass the cookie data. In other domains, we use wpml_get_cross_domain_language_data to handle the data and save the cookie.

    Example

    add_filter( 'wpml_cross_domain_language_data', 'pass_data_to_domain' ); // after plugins loaded
    
    // this will be executed on the original domain where we have access to the cookie
    function pass_data_to_domain( $xdomain_data ) {
    	if ( isset ( $_COOKIE[ 'cookie_name' ] ) ) {
    		$xdomain_data[ 'cookie_name' ] = $_COOKIE[ 'cookie_name' ];
    	}
       return $xdomain_data;
    }
    
    add_action( 'init', 'set_xdomain_data_cookie' );
    
    // this handle the xdomain_data and set the cookie
    function set_xdomain_data_cookie() {
    	$xdomain_data = apply_filters( 'wpml_get_cross_domain_language_data', array() );
    	if ( isset ( $xdomain_data[ 'cookie_name' ] ) ) {
    		setcookie( 'cookie_name', $xdomain_data[ 'cookie_name' ], time() + 30 * DAY_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN );
    	}
    }
    
    Back to the top

    wpml_loaded – Run actions after WPML is fully configured and loaded.

    availability:
    WPML Version: 3.2.1
    description:
    • To make sure a WPML dependent code is executed at the right time, this code should be hooked into the wpml_loaded action. This action is called after WPML is fully configured and loaded.
    • If we do not hook into this wpml_loaded, sometimes the WPML dependent code might be called too early. Then even if WPML is active and configured, we may not get expected results.
    • wpml_loaded is executed during the plugins_loaded action.
    • There are similar hooks for WPML String Translation wpml_st_loaded and WPML Translation Management wpml_tm_loaded. They are both hooked to wpml_loaded.
    type:
    action
    category:
    Miscellaneous
    parameters:
    add_action( 'wpml_loaded', callable $function_to_add );
    $function_to_add
    (callable) (Required) Your callback to be run when the filter is applied.
    hook example usage:

    Example

    function my_plugin_wpml_code() {
      // Run WPML dependent actions
      // These actions will be executed right after WPML is fully configured and loaded.
    }
    
    add_action( 'wpml_loaded', 'my_plugin_wpml_code' );
    
    Back to the top

    wpml_setting – Get the value of a WPML setting

    availability:
    WPML Version: 3.2
    description:

    Returns a WPML setting value

    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_setting', mixed|bool $default, string $key )
    $default
    (mixed|bool) (Required) The value to return if the settings key does not exist. Set to false if not using
    $key
    (string) (Required) The settings name key to return the value of
    hook example usage:

    Example

    // $is_wpml_configured will return TRUE if WPML is fully setup and FALSE if not.
    $is_wpml_configured = apply_filters( 'wpml_setting', false, 'setup_complete' );
    
    Back to the top

    wpml_sub_setting – Get the value of a WPML sub setting

    availability:
    WPML Version: 3.2
    description:

    Returns a WPML sub setting value.

    Attention

    • This hook is temporarily broken in WPML 3.3.6. We are working on it to fix this issue.
    • Currently you can use this hook wpml_setting for the same purpose.
    • Example:
      // Example: I need to get sub setting "font-current-normal" of "icl_lang_sel_config"
      
      $switcher = apply_filters( 'wpml_setting', false, 'icl_lang_sel_config' );
      echo $switcher['font-current-normal']; 
      
    type:
    filter
    category:
    Miscellaneous
    parameters:
    apply_filters( 'wpml_sub_setting', mixed|bool $default, string $key, string $sub_key )
    $default
    (mixed|bool) (Required) The value to return if the settings key does not exist. Set to false if not using
    $key
    (string) (Required) The settings name key the sub key belongs to
    $sub_key
    (string) (Required) The sub key to return the value of
    hook example usage:

    Example

    // $my_book_translation_option will return the translation option configured for the custom post type 'book'
    $my_book_translation_option = apply_filters( 'wpml_sub_setting', false, 'custom_posts_sync_option', 'book' );
    
    // $my_author_translation_option will return the translation option configured for the custom taxonomy 'author'
    $my_author_translation_option = apply_filters( 'wpml_sub_setting', false, 'taxonomies_sync_option', 'author' );
    
    
    Back to the top

    Updating Content

    wpml_set_translation_mode_for_post_type – Set a translation mode for a given post type.

    availability:
    WPML Version: 4.0.0
    description:

    Allows setting a translation mode for a given post type.

    type:
    action
    category:
    Updating Content
    parameters:
    do_action( 'wpml_set_translation_mode_for_post_type', $post_type, $translation_mode );
    $post_type
    (string) (Required) The slug of the post type you want to set translation mode for.
    $translation_mode
    (string) (Required) Translation mode to set, can be one of the following values:

    • “do_not_translate”
    • “translate”
    • “display_as_translated”
    hook example usage:

    Let’s say you have a custom post type “Books” (its slug is “book”) and you want to set it to use translation if available or fallback to default language.

    do_action( 'wpml_set_translation_mode_for_post_type', "book", "display_as_translated" );
    Back to the top