Polylang ability reference

Polylang's model: a language term per post and one shared map per set

Polylang attaches a language to a post as a taxonomy term, and records a translation set as a separate post_translations term whose description maps each language to a post id. That second term is shared by every member of the set. A change to one post therefore rewrites data the others depend on, which is the reason the ledger declines to treat a Polylang language change as a single-post restore.

Every call names a language by its Polylang slug, as returned by wppilot/polylang-list-languages, never by locale or display name; an unknown value is refused with polylang_language_not_found. The language list also carries each language's locale, W3C code, right-to-left flag, term id and its position in Polylang's own ordering, which helps when an agent has to match a hreflang tag or lay out a switcher in the order editors chose.

wppilot/polylang-list-content runs WP_Query with Polylang's lang query variable, so the language filter is applied by Polylang itself. Each row's translations map leaves out members that are trashed or auto-drafts, so a set can look incomplete in the listing while Polylang's own map still names the trashed post. The status filter accepts publish, draft, pending, private and future, with no single value for all of them.

Assign each language before you link a Polylang set

wppilot/polylang-link-content-translations assigns nothing. Every post in the map must already carry the language it is listed under, and the first one that does not stops the call with polylang_translation_language_mismatch, naming the post and language. A Polylang task therefore runs in two passes: wppilot/polylang-set-content-language for any post that is unassigned or wrong, then the link.

There is no source language and no option to keep or leave a group. The map goes to Polylang's pll_save_post_translations() as the whole relationship, and GoBuildWP compares what Polylang hands back with what was sent; any difference returns polylang_translation_link_failed. Because the map stands for the complete set, include every member that should stay linked, and on staging check whether a post you left out has dropped out of the switcher. Other refusals are polylang_invalid_translation_set (fewer than two or more than 50 pairs, an unconfigured slug, or a repeated post id) and polylang_translation_type_mismatch when the posts are of different types.

wppilot/polylang-set-content-language calls pll_set_post_language() and then reads the language back. A false return from Polylang gives polylang_language_assignment_failed, and asking for the language a post already holds returns changed: false without writing anything.

How a Polylang string write is planned, filtered and saved

Each item is resolved before anything is written. Naming it by original text always resolves, even when the string was never registered on this request. Naming it by name searches only the registrations Polylang recorded, so it fails with polylang_string_not_found when registration_complete is false, and with polylang_string_ambiguous when several groups use the name and no group was given.

The translation is trimmed and then passed to the pll_sanitize_string_translation filter with the name, group, original and previous value, in the order Polylang's Languages > Translations screen uses. The plan is built from the filtered result, so a filter that strips markup can turn an intended update into a no-op, and the result shows what was actually stored. An empty result removes the entry with delete_entry() rather than saving an empty string, because Polylang would export an empty entry as the original and count it as translated.

wppilot/polylang-bulk-set-string-translations groups items by language and saves each language once: it imports that language's pairs, applies every change, exports them to term meta, then re-reads the meta and checks each item, returning polylang_string_write_unverified for any that did not stick. Two items for the same string and language are rejected as polylang_duplicate_item rather than letting the second silently win. If Polylang's PLL_MO class or its model is not loaded on the request, every string call returns polylang_strings_unavailable.

Polylang under a restricted profile, and putting a change back

Under the Read Only safety profile the Polylang module shrinks to its reads. Under Production Safe every call loads, since none is classed as critical. The language and link writes are annotated destructive and go through the confirmation gate. The string writes are ordinary writes, so the gate does not stop them; their own checks do, and the bulk call is left unannotated on purpose so its dry run stays reachable without approval.

None of this can be undone with wppilot/rollback-change (see change ledger and rollback). To reverse a language change, call wppilot/polylang-set-content-language with the before value it returned, then relink the set from a wppilot/polylang-get-content-language read taken earlier. To reverse a string write, send its previous value back; a null previous means there was no translation, and sending an empty translation removes the one that was written.

A Polylang request worked through: French footer strings

Request: translate the footer tagline and copyright line into French. The agent runs wppilot/polylang-check-setup and notes string_translation.registration_complete, searches wppilot/polylang-list-strings with language fr and status untranslated, and copies each original verbatim. It sends both items to wppilot/polylang-bulk-set-string-translations with dry_run: true, shows the per-item plan, then repeats the same items with confirm: true.

On staging, filter Languages > Translations by French to see the stored values, load a French URL and read the footer, and compare each stored translation with what was sent, since the sanitising filter may have changed it. If a string the theme prints never appears in the list, open Languages > Translations once in wp-admin so Polylang records the theme's registrations, or pass the exact original text.

The module does not translate taxonomy terms, create translated posts, register new strings, or reach Polylang Pro services such as machine translation. Build the translated content with the ordinary post abilities first, then assign and link it here.