How to get translations programmatically

This tutorial is part of our MultilingualPress 2 documentation. In case you are using the newer version 3, please switch to MultilingualPress 3.

The most important API in MultilingualPress for you is probably the Language API. This API has a method get_translations() that you can use to get a prepared set of translations for posts of any post type, terms of any taxonomy, a search term, the front page or a blog page.

You can access that API with a filter:

$mlp_language_api = apply_filters( 'mlp_language_api', NULL );

MultilingualPress will transform that NULL value now into an instance of the class Mlp_Language_Api. In other words: The variable $mlp_language_api is an object now. But you should still test that, just in case the user has deactivated MultilingualPress:

$mlp_language_api = apply_filters( 'mlp_language_api', NULL );

if ( ! is_a( $mlp_language_api, 'Mlp_Language_Api_Interface' ) )
	return;

As you can see, you should test against the Interface Mlp_Language_Api_Interface, not against the concrete class. This enables other plugins to replace our implementation with a custom translation handler.

Today, we are looking just at $mlp_language_api->get_translations( $args );

Arguments for Mlp_Language_Api::get_translations()

$args is an array, we can pass some options here to tweak the results.

All parameters are optional. MultilingualPress will try to find proper values for them. We recommend to set the content_id for terms and posts though, because that is not always available, at least not in a reliable way.

Now let’s see how our code could look like:

$mlp_language_api = apply_filters( 'mlp_language_api', NULL );

if ( ! is_a( $mlp_language_api, 'Mlp_Language_Api_Interface' ) )
	return;

$args = array (
	'strict'               => TRUE,
	'include_base'         => TRUE
);

/** @var Mlp_Language_Api_Interface $mlp_language_api */
$translations = $mlp_language_api->get_translations( $args );

if ( empty ( $translations ) )
	return;

Note that $mlp_language_api->get_translations( $args ) will return an empty array if there are no translations even when we set include_base to TRUE.

Now, let’s say the translations are not empty. We get an array of objects, each an instance of Mlp_Translation which implements the Mlp_Translation_Interface. That sounds complicated, but it just means that we have a set of methods on each object to get information about the translation.

Methods for Mlp_Translation

The Mlp_Translation::get_language() object deserves an explanation. It has three public methods.

Methods for Mlp_Language

Example: Add translation links to the post content

Let’s see what we can do with all this code. The following example adds very simple translation links to the post content. It uses the first part of the language code and sets it to uppercase. The images are used too, if they are available.

add_filter( 'the_content', function( $content ) {

    if ( ! is_singular() )
        return $content;

    $mlp_language_api = apply_filters( 'mlp_language_api', NULL );

    if ( ! is_a( $mlp_language_api, 'Mlp_Language_Api_Interface' ) )
        return $content;

    $args = array (
        'strict'               => TRUE,
        'include_base'         => TRUE
    );

    /** @var Mlp_Language_Api_Interface $mlp_language_api */
    $translations = $mlp_language_api->get_translations( $args );

    if ( empty ( $translations ) )
        return $content;

    $links = array();

    /** @type Mlp_Translation_Interface $translation */
    foreach ( $translations as $translation ) {

        $current = $img = '';

        if ( $translation->get_target_site_id() === get_current_blog_id() )
            $current = ' class="current"';

        $img_url = $translation->get_icon_url();

        if ( '' !== (string) $img_url )
            $img = "<img src='$img_url' alt=''> ";

        $text = $translation->get_language()->get_name( 'language_short' );
        $text = mb_strtoupper( $text, 'UTF-8' );

        $links[] = sprintf(
            '<a href="%1$s" title="%2$s" %3$s>%4$s</a>',
            $translation->get_remote_url(),
            esc_attr( $translation->get_target_title() ),
            $current,
            $img . $text
        );
    }

    $links = '<p class="translations">'
        . join( ' <span class="separator">|</span> ', $links )
        . '</p>';

    return $content . $links;
});

The result should look like this:

Theme integration

You can use such a function in other places too, of course. In a theme you should add a custom action wherever you need it and assign a callback handler to that action. This way, your theme will not break when the user deactivates MultilingualPress.

So in a template file add this line:

do_action( 'translation_box' );

And in your functions.php create a callback function and register it for that action:

add_action( 'translation_box', 'show_mlp_translation' );

function show_mlp_translation() {
    // find and print translation links
}

Any questions or suggestions? Or do you have used this tutorial successfully? Please let me know.