polylang-rest-headless

Polylang REST and Headless

Use this skill when a client, plugin, or importer talks to WordPress REST and expects language-aware content.

Core Polylang and Polylang Pro behave differently:

Current language in REST

Polylang core reads a lang request parameter during REST dispatch:

GET /wp-json/wp/v2/posts?lang=fr

If lang is valid, pll_current_language() returns that language during the request. If an invalid lang is sent and a default language exists, Polylang falls back to the default language.

Do not rely on URL prefixes alone in custom REST routes. Read the language through Polylang:

register_rest_route( 'myplugin/v1', '/cards', array(
    'methods'             => WP_REST_Server::READABLE,
    'permission_callback' => '__return_true',
    'callback'            => static function ( WP_REST_Request $request ) {
        $lang = function_exists( 'pll_current_language' ) ? pll_current_language() : false;

        if ( ! $lang && function_exists( 'pll_default_language' ) ) {
            $lang = pll_default_language();
        }

        return rest_ensure_response( array(
            'lang' => $lang ?: get_locale(),
        ) );
    },
) );

For state-changing custom routes, still use normal REST permissions and nonces/auth. Language is not authorization.

Languages endpoint

Polylang core registers:

• GET /wp-json/pll/v1/languages
• POST /wp-json/pll/v1/languages
• GET|PUT|PATCH|DELETE /wp-json/pll/v1/languages/<term_id>
• GET /wp-json/pll/v1/languages/<slug>

The response schema includes fields such as term_id, name, slug, locale, w3c, is_rtl, flag_url, is_default, active, home_url, search_url, page_on_front, page_for_posts, fallbacks, and term_props.