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
• Add Language
  • Parameters
  • Response Properties
  • Example Request
• Update Language
  • Parameters
  • Example Request
• Delete Language
  • Parameters
  • Example Request
• General Remarks

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.