WPML REST API Language Parameter: How to Query and Create Translations

Your REST request returns a post—but not the translation your app expected. Or worse, a perfectly valid create request quietly produces content in the default language, leaving you to untangle the relationship afterward. When WPML sits on top of WordPress, language is more than a display preference: it changes which records you retrieve, what a new record becomes, and how translations must be connected.

The wpml rest api language parameter looks deceptively simple, yet endpoint support and behavior are not always as consistent as developers assume. A request that works for one resource may behave differently for another, and creating a translated post involves constraints that filtering an existing collection does not reveal.

If you are building a headless workflow, an integration, or a custom publishing pipeline, the details matter before they become production bugs. The difference between “the API returned content” and “the API returned the correct language version” is where the real work begins.

How Does the WPML REST API Language Parameter Work?

A REST request can look perfectly valid and still return the wrong translation. The deciding detail is often one small query argument: the wpml rest api language parameter. WPML must be installed, active, and configured first; it supplies the multilingual relationships and language context that WordPress core does not manage on its own.

Use lang to request a specific language

On WPML-supported REST endpoints, append lang to set the language context. For example, /wp-json/wp/v2/posts?lang=fr asks for French posts. The value must be the language code configured in WPML, not a locale guessed from convention. A site may use fr, fr-ca, or a custom code, so inspect the WPML language settings before hard-coding requests. The same pattern can be used when retrieving an individual resource where the route supports WPML language handling.

Understand the default-language fallback

When lang is omitted, developers commonly see content in the site’s default language. That behavior is convenient for a public feed, but unreliable for an integration that synchronizes translated content, builds a headless frontend, or checks translation status. Explicitly sending lang=fr, lang=de, or another configured code makes the request’s intent clear and prevents an unnoticed fallback from being mistaken for missing translations.

Know which endpoints expose language support

Support is not universal. Core REST endpoints for posts and pages are the usual starting point; custom post types also need to be registered with REST support and configured as translatable in WPML. Taxonomy routes may behave differently, while plugin-specific routes can implement their own filtering rules or ignore lang entirely. Test every route with known translated records, compare responses with and without the parameter, and confirm how creation or update requests assign language and translation relationships rather than assuming one endpoint’s behavior applies everywhere.

How to Retrieve WPML Content in a Specific Language

Query posts, pages, and custom post types

The decisive part of a multilingual REST request is usually one small addition: lang. With WPML’s REST API language support active, append the target language code to an ordinary WordPress endpoint:

• /wp-json/wp/v2/posts?lang=de&search=shipping&per_page=10&page=2

• /wp-json/wp/v2/pages?lang=fr&slug=about-us

• /wp-json/wp/v2/posts?lang=es&include=42,57

• /wp-json/wp/v2/products?lang=it&per_page=20

This wpml rest api language parameter does not replace normal REST filters; it narrows their results to one language. Pagination still matters: read X-WP-Total and X-WP-TotalPages from response headers, because totals can differ sharply by language. For a custom post type, its REST route must first be enabled, typically with show_in_rest => true; WPML cannot filter an endpoint WordPress does not expose.

Fetch translated terms and related content

Apply the same language context to term endpoints. For example, request /wp-json/wp/v2/categories?lang=de, /wp-json/wp/v2/tags?lang=de&search=angebot, or a registered custom taxonomy route such as /wp-json/wp/v2/product_cat?lang=fr. A category ID is not a language-neutral label: translated terms may have different IDs and slugs. When a client fetches a German post, then loads its categories, author-facing related posts, or taxonomy archives without lang=de, it can quietly assemble a mixed-language interface. Keep every related request in the same language context.

Inspect language and translation metadata in responses

Do not trust a successful 200 response alone. Inspect returned titles, slugs, term IDs, and any language or translation fields exposed by your WPML configuration. Translation relationship data may appear through WPML integrations, custom REST field registration, or endpoint-specific extensions rather than as a universal core REST field. In practice, test the exact route with two language codes and compare both the item returned and its metadata. That small verification step catches fallback content, untranslated records, and plugins that alter the response shape before they become production bugs.

Can You Create or Update Translations Through the REST API?

Reading translated content is the easy part. Writing it is where a single mistaken post ID can overwrite your default-language article instead of its French, German, or Spanish counterpart. The wpml rest api language parameter helps establish language context, but it does not, by itself, create a translation relationship.

Create content with the intended language context

Start with an authenticated POST request to the REST endpoint for a post type that supports the REST API. Supply the target language using WPML’s supported language handling, such as the relevant language parameter in the documented workflow. Authentication is a separate concern: an application password, OAuth-style setup, cookie authentication with a REST nonce, or another approved method must belong to a user who can create and edit that post type. A valid language code cannot compensate for insufficient WordPress capabilities.

Link the new post to its original translation

A translated post is more than text written in another language. WPML must know which source post it belongs to so language switchers, hreflang output, and translation status remain coherent. After creating the target-language resource, follow WPML’s documented REST API translation workflow to associate it with the original post and its translation group. Do not attempt to reproduce that logic by writing directly to WPML database tables. Those internal records carry relationships and metadata that can change between versions; bypassing WPML risks broken translation connections that are difficult to diagnose later.

Update the correct translation without overwriting another language

Use a retrieve-then-update pattern. First, identify the translation ID for the desired language through WPML’s supported API workflow. Then fetch that specific resource, confirm its language and source relationship, and send the update to that ID only. Finally, retrieve it again and verify both the changed fields and the language assignment.

• Never assume the source post ID is also the translated post ID.
• Log the source ID, target language, and target translation ID for every write.
• Test creates, links, and updates on a staging site before automating production imports.

That extra verification is cheap insurance. Translation automation is powerful precisely because it can make the same mistake hundreds of times very quickly.

WPML REST API Gotchas and Debugging Checklist

Why lang may appear to be ignored

A request can return perfectly valid JSON in the wrong language, which makes the wpml rest api language parameter deceptively hard to debug. Start with the language code: WPML usually expects the site’s configured code, such as de or fr, not a locale like de_DE. Then rule out cached responses; a cache that does not vary by query string can serve the English result for ?lang=fr.

Also confirm that the post type is set as translatable in WPML. Standard endpoints may respect language filtering, while an unsupported custom route may not. Finally, temporarily disable plugins that alter REST queries, especially search, security, caching, and content-filtering extensions.

Handle custom endpoints and headless front ends carefully

Custom REST routes do not automatically inherit every WPML behavior. In a custom callback, set WPML’s language context deliberately before running queries, use that context consistently, and restore it when needed so one request cannot affect another. Do not assume that adding lang to a route magically filters a hand-built WP_Query.

For headless builds, test the whole chain: language-aware API request, translated permalink, front-end route, and cache key. A CDN key that omits the language can undo otherwise correct WPML logic in production.

Test edge cases before deploying

• Query default and secondary languages, including records with no translation.
• Compare draft and published translations under authenticated and public requests.
• Verify pagination items, page counts, ordering, and translated taxonomy filters.
• Create a translation, then confirm its WPML relationship—not merely that two posts exist.
• Repeat requests with caches cold and warm, and after updating content.

Reduce translation costs when WPML content needs localization

For teams already committed to WPML, LATW AI Translator for WPML is an add-on, not a replacement for WPML. It works inside WPML’s translation workflow and sends content directly from WordPress to supported AI or translation providers using your own API key. That BYOK approach can reduce the cost of creating the localized posts, fields, and metadata that your API later serves, while WPML continues to manage language relationships, URLs, and multilingual infrastructure.

Make Language an Explicit Part of Every API Contract

The WPML REST API language parameter is the key to reliable language-aware reads, but creating a usable translation takes more than posting translated content: the new item must be assigned the intended language and linked to its source within WPML’s translation relationship. Treat those steps as part of the same operation, not as optional metadata to fix later.

As you build integrations, make language explicit in every request, use WPML-supported APIs rather than writing to its database directly, and test each endpoint’s behavior in staging before deploying. A multilingual API integration is dependable only when language is handled as deliberately as content.