Skip Navigation
Updated
February 27, 2023

Many themes display special posts, pages and categories specially, usually based on IDs. For example, a ‘Featured’ posts section in the home page, or highlighted categories.

In some cases, these IDs are hard-coded into the theme’s PHP and in others, the user selects them in the theme’s setting screen.

To display correctly, the theme needs to select the IDs per language. In WPML, IDs for posts, pages, categories and tags change when the language changes, so the theme needs to use the correct IDs of the active language.

WPML includes two options for achieving this.

You can either enable the automatic ID adjustment or use the wpml_object_id manually in your theme.

Which Option to Use?

The automatic ID adjustment requires no changes in your code. You can use it with any theme and everything “just works”. The down-side for using it is slightly increased processing time and DB access, as WPML will hook to many functions and check that the output is correct for the active language.

Manual ID adjustment using the wpml_object_id function will achieve the same results and can be more efficient in terms of processing. However, it requires significant coding in the theme.

If you’re building a theme from scratch, you should consider using wpml_object_id to do it manually. If you’re starting with an existing theme, hacking and modifying the theme might not be realistic and the automated ID adjustment is probably the way to go.

In any case, by using any caching plugin, the performance impact of this operation are reduced to none. Caching is always recommended for sites of any size. WPML runs fine with WP Super Cache and W3 Total Cache (which we also use on different sites).

1) Automatically Adjust IDs

WPML can hook to WordPress API functions, detect when specific items are loaded and adjust IDs so that the results are adjusted for the active language.

This functionality is enabled by default and can be accessed via WPMLLanguages:

Adjust IDs for multilingual functionality

This will automatically adjust all IDs and can be used in any WordPress theme that uses the API correctly (almost any theme you can find).

2) Manually, using the wpml_object_id function

Alternatively, if the automatic ID adjustment is off, you can use the wpml_object_id function to achieve the same manually.

apply_filters( ‘wpml_object_id’, int $element_id, string $element_type, bool $return_original_if_missing, mixed $ulanguage_code )

Note: For WPML versions >=3.2 please use the wpml_object_id filter hook. Since WPML 3.3, icl_object_id function has been tagged as deprecated and removed completely in 3.3

Example usage

echo apply_filters( 'wpml_object_id', 4, 'category', TRUE  );

Return the category ID in the current language for category ID 4. If the translation is missing it will return the original (here: category ID 4).

Please, check our API page to see other examples and find a more detailed information about its usage

Translating arrays of IDs

Many times you need to convert an entire array of object IDs (most commonly category IDs). To do this, you can use the following function:

function lang_object_ids($object_id, $type) {
    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;
    } else {
  return apply_filters( 'wpml_object_id', $object_id, $type, true, $current_language );
 }
}

This function also accepts the object type as an argument.

For example, to get an array of category IDs for categories 1,3 and 6 we’ll call:

lang_object_ids(array(1,3,6),'category')

Displaying page elements in different languages

The optional ulanguage_code parameter allows mixing page elements in different languages.

For example, if you have an image gallery and don’t want to duplicate the images per language, follow this:

  1. Get the ID of the page in the language in which the gallery exists.
  2. Loop on the images for that page and display them.