Skip Navigation
June 9, 2021

Developers can create their own custom language switchers using the icl_get_languages API call from WPML. In this tutorial, you will find the full details of icl_get_languages and examples of custom language switchers built with it.
Quick overview:

  1. Call icl_get_languages to get the list of translations for the currently-displayed page
  2. Write your own PHP function that renders the language switcher
  3. Place your language switcher in your theme

Getting the list of (other) languages

Use icl_get_languages() to get a list of translations for any page. If you are using WPML 3.2 or above, you should consider using the similar hook filter wpml_active_languages.



* N=0/1
* KEY=id/code/name/custom (name -> translated_name), (default: id)
* DIR=asc/desc (default: asc)
* link_empty_to = str (default: empty, 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)


  • The skip_missing parameter tells the function how to treat languages with no translations.
  • The combination of orderby and order allows creating the drop-down language switcher or language switchers where languages always display in the same position.
  • The custom order can be defined in the WordPress admin under WPML » Languages » Language Switcher Options

The function returns an array with entries per language. For example, for a WordPress site running English, French and Italian, it will return this:

 [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

Each language has its own array of parameters, which your theme function can use to build any language selector.

  • id: Internal reference id
  • active: This is the currently active language (exactly one language is active)
  • native_name: The native name of the language (never translated)
  • translated_name: The name of the language translated to the currently active language
  • country_flag_url: The URL to a PNG image with the country flag
  • url: The link to the translation in that language
  • missing: 1 if the translation for that element is missing, 0 if it it exists.

Handling missing translations

Some pages may not be translated to all languages. You can tell icl_get_languages what to return for languages with no translations.

If ‘skip_missing=1’, these languages will not appear in the output. If ‘skip_missing=0’, all the languages will appear and languages with missing translations will link back to the home page in that language.

How to use in your theme functions

You can build your own language switchers in whatever way you choose. Here, we’ll show two popular uses.

The example PHP functions we’re showing here should go in to your functions.php file (in the theme folder) – not added to the plugin.

This post is also available in…

Supposing you want to add a line, at the bottom (or top) of each post, saying in which other languages it’s available. This function should only return existing translated posts and if no translation is available, it shouldn’t output anything.

function icl_post_languages(){
  $languages = icl_get_languages('skip_missing=1');
  if(1 < count($languages)){
    echo __('This post is also available in: ');
    foreach($languages as $l){
      if(!$l['active']) $langs[] = '<a href="'.$l['url'].'">'.$l['translated_name'].'</a>';
    echo join(', ', $langs);

What this function does is:

  1. Get the list of languages from WPML – $languages = icl_get_languages(‘skip_missing=1’);
  2. Check that there’s more than one language for this post – if(1 < count($languages))
  3. Create the output, skipping the currently displayed language – if(!$l[‘active’])


  1. The message goes through gettext. This is very important, so that this message, which you’ll append to posts in different languages will appear in the correct language:  __(‘This post is also available in: ‘);
  2. The language names used are the translated language names. This would guarantee that the entire sentence is written in the correct language: $l[‘translated_name’]

The result is this:

Message about post available in other languages
Message about post available in other languages

To include this message in posts, add a call to icl_post_languages() from single.php.

Even if you have a language selector at the top of the page, it’s a good idea to add a list of language names and flags to the footer. Many people immediately scroll down the the bottom of the page, to get a better idea of what’s ahead, so placing a prominent language switcher there is likely to help your foreign visitors.

function languages_list_footer(){
    $languages = icl_get_languages('skip_missing=0&orderby=code');
        echo '<div id="footer_language_list"><ul>';
        foreach($languages as $l){
            echo '<li>';
                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 icl_disp_language($l['native_name'], $l['translated_name']);
            if(!$l['active']) echo '</a>';
            echo '</li>';
        echo '</ul></div>';

This function does the following:

  1. If there’s any translation language, creates a DIV and starts an unordered list: if(!empty($languages)){ echo ‘<div id=”footer_language_list”><ul>’;
  2. Goes through each of the languages and adds it as a list item.
  3. If it’s not the active language, also link to that page in that language: if(!$l[‘active’]) echo ‘<a href=”‘.$l[‘url’].'”>’;
  4. Adds the language flag: <img src=”‘.$l[‘country_flag_url’].'” alt=”‘.$l[‘language_code’].'” width=”18″ height=”12″ />
  5. Add both native and translated language names, if they’re different: echo icl_disp_language($l[‘native_name’], $l[‘translated_name’]);

The icl_disp_language() function is created by WPML. What it does is check if the two arguments (native_language_name, translated_language_name) are different. If so, it returns them both, otherwise, it returns them just once.

We should also add some CSS to style this languages list. This CSS will center the languages list in your footer and format it a bit:

  margin-bottom: 25px;
  text-align: center;

#footer_language_list ul{
  list-style: none;

#footer_language_list ul li img{

#footer_language_list ul li{
  margin:0 5px 0 5px;

#footer_language_list ul li a, #footer_language_list ul li a:visited{
  color: #fff;

#footer_language_list ul li a:hover, #footer_language_list ul li a:active{
  color: #fff;

Here is the language switcher:

Language footer
Language footer

To add it to your theme, add the call to languages_list_footer to the footer.php file.

* Note: you can easily change turn this horizontal language switcher into a vertical language switcher. Just remove the display: inline statement from the CSS.

Language selector with flags only

Simple function for displaying flags linked to the translations of the current page.

Language selector with flags only
function language_selector_flags(){
    $languages = icl_get_languages('skip_missing=0&orderby=code');
        foreach($languages as $l){
            if(!$l['active']) echo '<a class="wpml-ls-item" href="'.$l['url'].'">';
            echo '<img src="'.$l['country_flag_url'].'" height="12" alt="'.$l['language_code'].'" width="18" />';
            if(!$l['active']) echo '</a>';

The output of this function needs to be styled separately. For instance placing the function into a div block and defining custom styles for the img tags.

The CSS:
#flags_language_selector img{
      border:1px solid #333;
Flags language selector

Language switcher displaying only inactive languages

The code example in this article can be used to create a language switcher with the following characteristics:
  • Displays horizontally
  • Attaches to a specific menu
  • Uses language flags and native names
  • Shows only inactive languages
You should add this code to your theme’s functions.php file. Even better solution is to add it to the functions.php of your theme’s child theme. By default, the code is working well with the default WordPress themes (Twenty Sixteen, Twenty Fifteen, etc.) with theme_location == 'primary'.
This is the language switcher in the Twenty Sixteen theme when the current language is English.
This is the result in the Twenty Sixteen theme when the current language is English.

Making the code work with your theme

Other themes may use other theme locations. Therefore if the code is not working for your theme, please follow the following steps to get it working.
  1. Uncomment the line //echo "args:
    "; print_r($args); echo "


    In other words, remove the double slashes (//) at the beginning of the line containing the aforementioned code.
  2. Visit your site’s front-end. You will see theme location(s) like [theme_location] => my-theme-location.
  3. Select the menu location you want, e.g: my-theme-location, and change the line:
if ( $languages && $args->theme_location == 'primary') {
if ( $languages && $args->theme_location == 'my-theme-location') {
You are not sure about which is the right location to use, you can simply try the menu locations one-by-one.
  1. Revert the changes we made in the first step, so that the line is the same as the original code.

The code

 // Filter wp_nav_menu() to add additional links and other output // Show only other language in language switcher // Use the new filter: add_filter('wp_nav_menu_items', 'new_nav_menu_items', 10, 2); function new_nav_menu_items($items, $args) { // uncomment this to find your theme's menu location //echo "args:<pre>"; print_r($args); echo "</pre>"; // get languages $languages = apply_filters( 'wpml_active_languages', NULL, 'skip_missing=0' ); // add $args->theme_location == 'primary-menu' in the conditional if we want to specify the menu location. if ( $languages && $args->theme_location == 'primary') { if(!empty($languages)){ foreach($languages as $l){ if(!$l['active']){ // flag with native name $items = $items . ' <li class="menu-item"><a href="' . $l['url'] . '"><img src="' . $l['country_flag_url'] . '" height="12" alt="' . $l['language_code'] . '" width="18" /> ' . $l['native_name'] . '</a></li> '; //only flag //$items = $items . ' <li class="menu-item menu-item-language"><a href="' . $l['url'] . '"><img src="' . $l['country_flag_url'] . '" height="12" alt="' . $l['language_code'] . '" width="18" /></a></li> '; } } } } return $items; } 

Replacing the country flags and changing language names

WPML includes a GUI for editing language information. Go to WPML->Languages and click on Edit languages. You will be able to change the language names, edit their locale values and choose different flags.