polylang-language-api

Polylang Language API

Use this skill when plugin or classic theme code needs to detect, list, switch, or route by Polylang languages.

Polylang's public API lives in wp-content/plugins/polylang/src/api.php. Prefer those functions over PLL()->... internals. The PLL() accessor exists, but the source itself says API functions are preferred because internals may change.

Load and guard

Polylang may be inactive, may not have languages yet, or may be running in admin/REST/CLI without a current language. Always guard public API use:

if ( ! function_exists( 'pll_current_language' ) ) {
    return;
}

$lang = pll_current_language();
if ( ! $lang ) {
    $lang = pll_default_language();
}

if ( ! $lang ) {
    return;
}

Do not read $_GET['lang'] directly as your language model. Let Polylang define the current language, then read it through pll_current_language().

Current and default language

pll_current_language( $field = 'slug' ) returns the current language on frontend, the admin language filter in admin, and false if no current language exists. Useful fields include:

$slug   = pll_current_language();          // e.g. "en"
$locale = pll_current_language( 'locale' ); // e.g. "en_US"
$name   = pll_current_language( 'name' );
$lang   = pll_current_language( \OBJECT ); // PLL_Language object.

pll_default_language( $field = 'slug' ) has the same field behavior and returns false if no default language exists yet.

Since Polylang 3.4, composite language term properties are accepted:

$term_taxonomy_id = pll_current_language( 'language:term_taxonomy_id' );
$term_language_tt = pll_default_language( 'term_language:term_taxonomy_id' );

Use composite fields only when you need SQL joins or taxonomy term IDs. For most code, use slugs.

List languages

Use pll_languages_list() for language lists:

$slugs = pll_languages_list();

$locales = pll_languages_list( array(
    'fields' => 'locale',
) );

$active_slugs = pll_languages_list( array(
    'fields'     => 'slug',
    'hide_empty' => true,
) );