REST API

PerfLocale exposes a RESTful API under the perflocale/v1 namespace for managing languages, translations, strings, imports, and more.

All endpoints require authentication via WordPress cookies or application passwords. Write operations require appropriate capabilities.

Base URL: /wp-json/perflocale/v1/

Authentication & Permissions

Level	Capability	Used By
Public	None	`GET /languages`, `GET /languages/{slug}`
Translate	`perflocale_translate`	Translation CRUD, strings list, workflow
Machine Translation	`perflocale_use_mt`	`POST /machine-translate`
Languages	`perflocale_manage_languages`	Language create/update/delete, MT test
Import/Export	`perflocale_import_export`	Import, XLIFF export/import
Admin	`manage_options`	String scan, webhooks

All write endpoints are protected by WordPress REST nonce verification.

Restricting Public Reads

The language endpoints (GET /languages, GET /languages/{slug}) are public by default because every field they expose - slug, locale, name, native name, flag, RTL flag, default flag - is already rendered to anonymous visitors via the language switcher, hreflang tags, and URL structure. There is nothing private to protect.

Site owners who still want to require authentication for these reads can hook the perflocale/api/languages_public filter. When it returns false, both endpoints require the read capability (any logged-in user). Write endpoints are unaffected - they always require perflocale_manage_languages.

// Drop this in a MU-plugin or functions.php to lock down /languages.
add_filter( 'perflocale/api/languages_public', '__return_false' );

The GET /config endpoint is already opt-in: the route is only registered when Edge Worker Integration is enabled in Settings → Advanced. On a fresh install it responds with 404.

Languages

List Languages

GET /perflocale/v1/languages

Returns all configured languages. Public by default - no authentication required. Can be gated behind login via the perflocale/api/languages_public filter.

Response:

{
	"success": true,
	"data": {
		"languages": [
			{
				"id": 1,
				"slug": "en",
				"locale": "en_US",
				"name": "English",
				"native_name": "English",
				"flag": "en",
				"is_default": false,
				"is_active": true,
				"text_direction": "ltr"
			}
		]
	}
}

Get Single Language

GET /perflocale/v1/languages/{slug}

Parameters:

slug (string, required) - Language slug (e.g. en, fr, de).

Create Language

POST /perflocale/v1/languages

Requires: perflocale_manage_languages

Body (JSON):

{
	"slug": "fr",
	"locale": "fr_FR",
	"name": "French",
	"native_name": "Français",
	"flag": "fr",
	"is_active": true,
	"text_direction": "ltr"
}

Update Language

PUT /perflocale/v1/languages/{slug}

Requires: perflocale_manage_languages

Body: Same fields as create (partial updates supported).

Delete Language

DELETE /perflocale/v1/languages/{slug}

Requires: perflocale_manage_languages

Reorder Languages

POST /perflocale/v1/languages/reorder

Requires: perflocale_manage_languages

Body:

{
	"order":  [3, 1, 2, 4],
	"offset": 0
}

order is a list of language IDs in the desired display order. offset is optional (default 0) and lets you reorder a contiguous slice without sending the full list — useful for paginated UIs.

Response:

{
	"success": true,
	"data": { "reordered": 4 }
}

Translations

Get Translations for a Post

GET /perflocale/v1/translations/post/{id}

Requires: edit_post capability for the specific post.

Response:

{
	"success": true,
	"data": {
		"languages": [
			{
				"slug": "en",
				"language_id": 1,
				"name": "English",
				"native_name": "English",
				"is_current": true,
				"is_default": false,
				"has_translation": true,
				"post_id": 42,
				"status": "published",
				"status_label": "Published",
				"edit_url": "https://example.com/wp-admin/post.php?post=42&action=edit",
				"workflow": null,
				"assigned_to": 0,
				"priority": "normal",
				"deadline": ""
			},
			{
				"slug": "de",
				"language_id": 3,
				"has_translation": false,
				"post_id": null,
				"status": null
			}
		]
	}
}

Also supports terms:

GET /perflocale/v1/translations/term/{id}

Create Translation

POST /perflocale/v1/translations/post/{id}

Requires: edit_post capability for the source post.

Body:

{
	"target_lang": "de",
	"copy_content": true
}

Response:

{
	"success": true,
	"data": {
		"post_id": 99,
		"edit_url": "https://example.com/wp-admin/post.php?post=99&action=edit"
	}
}

Update Translation

PUT /perflocale/v1/translations/post/{id}/{lang}

Requires: edit_post capability for the translated post.

Body (partial updates supported):

{
	"title": "Translated Title",
	"content": "<p>Translated content.</p>",
	"excerpt": "Short description",
	"status": "publish"
}

Delete Translation

DELETE /perflocale/v1/translations/post/{id}/{lang}

Requires: delete_post capability for the translated post.

Permanently deletes the translated post and removes the translation link.

Assign Language to Existing Post

POST /perflocale/v1/translations/post/{id}/language

Tag a previously-untagged post with a language so it joins (or seeds) a translation group. Only valid for posts that have no language yet — to prevent accidental re-parenting of an existing translation group, posts that already belong to a group return already_assigned (HTTP 409).

Requires: edit_post capability for the post. Only {type}=post is accepted; terms cannot be reassigned this way.

Body:

{ "slug": "de" }

Response:

{
	"success": true,
	"data": { "post_id": 42, "slug": "de" }
}

Workflow

Only available when the workflow feature is enabled in settings.

Update Workflow Status

PUT /perflocale/v1/workflow/{post_id}/{language_id}

Requires: perflocale_manage_translations

Body:

{
	"status": "assigned",
	"assigned_to": 5,
	"priority": "high",
	"deadline": "2026-04-15",
	"notes": "Please translate by end of week."
}

Available statuses: unassigned, assigned, in_progress, review, approved, published

Get Translators

GET /perflocale/v1/workflow/users

Returns users with perflocale_translate or perflocale_manage_translations capabilities.

Response:

{
	"success": true,
	"data": {
		"users": [
			{ "id": 5, "name": "Jane Translator" }
		]
	}
}

Strings

List Translatable Strings

GET /perflocale/v1/strings

Requires: perflocale_translate

Query Parameters:

domain (string) - Filter by text domain (e.g. woocommerce).
per_page (int) - Results per page. Default: 50, max: 100.
offset (int) - Pagination offset. Default: 0.

Response:

{
	"success": true,
	"data": {
		"strings": [
			{
				"id": 1,
				"domain": "woocommerce",
				"context": "",
				"original": "Add to cart",
				"file_path": "templates/single-product/add-to-cart.php",
				"line_number": 42
			}
		]
	}
}

Scan for Strings

POST /perflocale/v1/strings/scan

Requires: manage_options

Body:

{
	"target": "plugins",
	"domain": "woocommerce"
}

Available targets: theme, plugins, parent

Machine Translation

Only available when machine translation is enabled in settings.

Translate a Post

POST /perflocale/v1/machine-translate

Requires: perflocale_use_mt

Body:

{
	"post_id": 42,
	"target_lang": "de",
	"provider": "deepl"
}

Available providers: deepl, google, microsoft, libretranslate (depends on configuration).

Translate a Single Text Block

POST /perflocale/v1/block-translate

Requires: perflocale_use_mt

Stateless single-string translation - no post, no group, no DB writes. Powers the Gutenberg block-toolbar “Translate with MT” action but usable by any caller that wants to translate a snippet without touching the post store.

Body:

{
	"text": "Hello, world.",
	"source_lang": "en",
	"target_lang": "de",
	"provider": "deepl"
}

Response:

{
	"success": true,
	"data": {
		"translated": "Hallo, Welt.",
		"provider": "deepl"
	}
}

Maximum input length: 50000 characters.
Provider response is passed through the same wp_kses_post-based allowlist used by post translation, so HTML snippets are safe to apply to block attributes.
Shares the per-user hourly budget with /machine-translate (500/hour by default, filterable via perflocale/mt/rate_limit).
When source_lang equals target_lang, returns the input unchanged.

Translate a Block from its Source Sibling

POST /perflocale/v1/block-translate/from-source

Requires: perflocale_use_mt + edit_post on target_post_id

Sibling-aware "Fill in from source" endpoint. Locates the corresponding block in the post's source-language sibling using a position-path walk, extracts the relevant text attribute, and machine-translates it into the editing language. Source language is derived server-side from the source post; the caller never has to supply it.

Body:

{
	"target_post_id": 117,
	"block_path":     [3, 1, 2],
	"target_lang":    "de",
	"source_attr":    "",
	"provider":       ""
}

target_post_id - the sibling currently being edited (the translation, not the source).
block_path - position path into the block tree: [3, 1, 2] = top-level index 3, then inner index 1, then inner index 2. The server walks the same indices in the source post's tree.
target_lang - language slug of the post being edited.
source_attr - optional. Which attribute to extract from the source block (e.g. "content"). When omitted, the server tries content / text / value / caption / summary / alt / title / placeholder in order and picks the longest-text candidate.
provider - optional MT provider override.

Returns the same shape as /block-translate plus the resolved source_attr so the editor knows which attribute to write back.