WPML ability reference

Trids, element types and the icl_translations row

WPML does not keep a post's language in post meta. Each translatable element has a row in WPML's icl_translations table holding a language code and a trid, the id of the translation group it belongs to; every member of one group shares that trid. The language and grouping abilities touch that row only through WPML's published hooks (wpml_element_language_details, wpml_set_element_language_details, wpml_get_element_translations), so WPML's own actions and caches stay in step with what the agent changed.

Those hooks disagree about spelling. The write hook and the group lookup want a prefixed element type such as post_page or tax_category, while the details hook wants the bare name. GoBuildWP derives the prefixed form from the post itself, so an agent never passes it to wppilot/wpml-get-content-language, wppilot/wpml-set-content-language or wppilot/wpml-link-content-translations. The one call that takes an element type from the caller, wppilot/wpml-get-translation, expects the bare post type or taxonomy name. An unregistered name is refused with wpml_element_type_not_found, and a registered type WPML does not translate with wpml_element_type_not_translated, so a miss is never mistaken for a missing translation.

Two reads answer the translatable-type question slightly differently. wppilot/wpml-check-setup only walks post types and taxonomies that have an admin interface, while wppilot/wpml-list-translatable-types walks every registered type and adds public and built-in flags. Use the second when a hidden custom post type is involved.

Why a WPML group link commits whole or not at all

wppilot/wpml-link-content-translations runs inside a database transaction. It first asks MySQL which engine stores icl_translations, and only an InnoDB table is linked; anything that cannot start a transaction gets wpml_atomic_link_unavailable with nothing changed. Inside the transaction it writes the source post, reads it back, then writes and verifies each other member against the same trid. A member that does not come back in the expected language and group rolls every change back, flushes the object cache and returns wpml_translation_link_failed naming the post. A failed commit returns wpml_translation_commit_failed.

Before opening the transaction it refuses a map that would push an existing member out of its slot: if the source post's group already holds a different post for one of the listed languages, the call stops with wpml_translation_language_occupied. Linking also assigns each listed language as it attaches a post, recording the source language as the one it was translated from, so a post reporting has_language: false can go straight into a link without a separate assignment.

For a single post, wppilot/wpml-set-content-language reads the post back after writing and returns wpml_language_assignment_failed if WPML did not keep the language; the source attributes that to a type being switched out of translation between the check and the write. Asking for the language a post already has, with keep_group left on, returns changed: false and writes nothing.

Neither group write can be reversed with wppilot/rollback-change, because the change lives in icl_translations, which the change ledger records as irreversible. Keep the wppilot/wpml-get-content-language output from before the change: it lists every member with its id and whether it was the original, which is what a manual rebuild needs.

String Translation refusals: gettext context, packages and source language

The module registers without WPML String Translation, but every string call refuses with wpml_string_translation_missing unless the add-on is loaded with icl_add_string_translation and the wpml_register_single_string action. wppilot/wpml-check-setup reports it under companions.string_translation.

A domain and name pair is only unique together with its gettext context. When the pair matches more than one row, a write is refused with wpml_string_ambiguous instead of picking one; use the string_id from wppilot/wpml-list-strings. Other refusals to recognise are wpml_string_in_package for builder and form strings, wpml_string_source_language when the target language is the string's own source (change the source text with wppilot/wpml-register-string instead), and wpml_string_not_found when nothing matches.

Each write is read back from the icl_string_translations table rather than WPML's per-request cache, and a value or status that did not land returns wpml_string_write_unverified. Line endings are normalised to single newlines before comparing, because WPML stores them that way, so a value that differs only in its line breaks plans as unchanged. Registration is checked the same way; wpml_string_register_unverified points at String Translation's settings for the language that was given.

Status filters map onto WPML's own codes, 10 for complete and 3 for needs-update. The waiting-for-translator and in-progress states that Translation Management sets are reported but cannot be written from here, and a string is never listed as untranslated in its own source language.

Profiles, confirmation and the WPML bulk dry run

Under the Read Only safety profile only the WPML reads remain. Under Production Safe everything loads, since nothing here is classed as critical. The language and group writes are annotated destructive, so the confirmation gate wants confirm: true, or a person's approval when the site's confirmation mode is human. wppilot/wpml-bulk-set-string-translations is deliberately left unannotated so its dry run stays reachable without that gate; the real run enforces confirm itself and answers wppilot_confirmation_required with the item count when it is missing. The single string write and the registration ask for confirm only when they would overwrite an existing different value.

What stays in WPML's Translation Management screens

Translation jobs are not wrapped. The source notes that WPML publishes no stable hook for listing or creating them, and that the batch objects its own screens pass around differ between WPML releases, so sending content to translators, assigning jobs and reviewing them stays in WPML > Translation Management. The module also never changes WPML configuration (languages, translatable types, translation mode), has no term-language write, and leaves WooCommerce Multilingual pricing and attributes alone, although check-setup reports whether WCML is active.

A typical request: link our Spanish contact page to the English one so the switcher shows it. The agent runs wppilot/wpml-check-setup, confirms page is in translated_post_types, finds both ids with wppilot/wpml-list-content (once per language), reads each with wppilot/wpml-get-content-language, and after approval calls wppilot/wpml-link-content-translations with source_language en. On staging, a second read should show one trid with the English page as original, the switcher on the English page should reach the Spanish one, and wppilot/wpml-get-translation with element_type page and language es should resolve the English id to the Spanish id.