polylang-object-translations

Polylang Object Translations

Use this skill when code needs to read or write the relationship between translated posts or translated terms.

Polylang stores language and translation relationships through private taxonomies, not custom tables:

Do not write those terms or term descriptions directly. Use Polylang APIs so caches, cleanup, validation, and synchronization hooks run.

Resolve translated IDs

For posts:

$translated_id = pll_get_post( $post_id, 'fr' );

if ( $translated_id > 0 ) {
    $post = get_post( $translated_id );
}

For terms:

$translated_term_id = pll_get_term( $term_id, 'fr' );

Important return behavior in Polylang 3.8.5:

• pll_get_post() returns an integer ID.
• pll_get_term() returns an integer ID.
• Missing translation, invalid language, or object without language returns 0, not false.
• If the requested language is the object's own language, the original ID is returned.

When $lang is omitted, both functions use pll_current_language(). In cron, CLI, imports, and many admin tasks, pass the language explicitly.

Read language and groups

$post_lang = pll_get_post_language( $post_id );          // slug or false.
$term_lang = pll_get_term_language( $term_id, 'locale' );
$lang_obj  = pll_get_post_language( $post_id, \OBJECT );

$post_translations = pll_get_post_translations( $post_id );
$term_translations = pll_get_term_translations( $term_id );

Translation arrays are keyed by language slug and contain object IDs:

array(
    'en' => 123,
    'fr' => 456,
)

Only trust arrays returned by Polylang. The model validates languages and object IDs before saving.

Create posts with language

Polylang 3.7+ provides pll_insert_post() and pll_update_post() wrappers:

$post_id = pll_insert_post(
    array(
        'post_type'   => 'book',
        'post_status' => 'publish',
        'post_title'  => 'Hello',
    ),
    'en'
);

if ( is_wp_error( $post_id ) ) {
    return $post_id;
}