Languages REST API

The Languages REST API is now included with Polylang (from 3.7). This API provides programmatic access to manage languages in Polylang through HTTP endpoints. It allows listing, create, update, and delete languages in your WordPress installation. All endpoints are accessible via /wp-json/pll/v1/languages route and support standard REST operations.

This documentation covers the available endpoints, their parameters, and example usage to help integrate Polylang’s language management capabilities into applications.

Table of Contents

List Languages

Retrieves a list of all configured languages.

GET /wp-json/pll/v1/languages

The response includes all language properties as defined in the schema, including read-only properties like flag_url, is_default, and home_url.

Notes:

  1. manage_options capability is required when request is made with context set to edit.
  2. Deactivated languages (Polylang Pro feature) are also listed.

Add Language

Creates a new language.

POST /wp-json/pll/v1/languages

Parameters

Parameter Type Required Description
locale string Yes WordPress locale for the language (e.g., en_US). Must match pattern: ^[a-z]{2,3}(?:_[A-Z]{2})?(?:_[a-z0-9]+)?$.
name string No Display name for the language (e.g., “English”).
slug string No Language code, preferably 2-letters ISO 639-1 (e.g., “en”). Must match pattern: ^[a-z][a-z0-9_-]*$.
is_rtl boolean No Text direction. Set to true for right-to-left languages.
flag_code string No Flag code corresponding to ISO 3166-1 (e.g., “us” for United States flag).
term_group integer No Position of the language in the language switcher. Defaults to 0.
no_default_cat boolean No Whether to skip creating the default category for this language. Defaults to false.

Notes:

  1. If not provided, the default values for name, slug, is_rtl, and flag_code comes from Polylang’s internal database.

Response Properties

The API returns a language object with the following notable properties:

Property Type Description
term_id integer Unique identifier for the language.
w3c string W3C locale for the language (e.g., “en-US”).
facebook string Facebook locale for the language.
flag_url string URL to the flag image.
flag string HTML tag for the flag.
is_default boolean Whether this is the default language.
active boolean Whether the language is active.
home_url string Home URL in this language.
search_url string Search URL in this language.
host string Host for this language.
fallbacks array List of language locale fallbacks.
term_props object Language properties for posts and terms.

Example Request

POST /wp-json/pll/v1/languages

{
  "locale": "fr_FR",
  "name": "Français",
  "slug": "fr",
  "flag_code": "fr"
}

Update Language

Updates an existing language.

/wp-json/pll/v1/languages/{term_id}

Parameters

Parameter Type Required Description
term_id integer Yes The term_id of the language to update.
locale string No WordPress locale for the language (e.g., en_US). Must match pattern: ^[a-z]{2,3}(?:_[A-Z]{2})?(?:_[a-z0-9]+)?$.
name string No Display name for the language (e.g., “English”).
slug string No Language code, preferably 2-letters ISO 639-1 (e.g., “en”). Must match pattern: ^[a-z][a-z0-9_-]*$.
is_rtl boolean No Text direction. Set to true for right-to-left languages.
flag_code string No Flag code corresponding to ISO 3166-1 (e.g., “us” for United States flag).
term_group integer No Position of the language in the language switcher. Defaults to 0.

Example Request

PUT /wp-json/pll/v1/languages/42

{
  "name": "Français",
  "flag_code": "fr"
}

The response will include the updated language object with all properties as described in the response properties section above.

Delete Language

Deletes an existing language.

DELETE /wp-json/pll/v1/languages/{term_id}

Parameters

Parameter Type Required Description
term_id integer Yes The term_id of the language to delete.

Example Request

DELETE /wp-json/pll/v1/languages/42

The response will return true on successful deletion along previous data, such as:

{
  "deleted": true,
  "previous": "..."
}

General Remarks

  • All endpoints support batch requests through the v1 batch API.
  • Delete, create and update endpoints require authentication with a user that has the manage_options capability.
  • The API enforces strict validation of parameter types and formats.
  • The complete API schema is discoverable on OPTIONS /wp-json/pll/v1/languages endpoint. This provides detailed information about available endpoints, methods, parameters, and their constraints.