WPML: compatibility overview (orient)

For developers making a plugin or theme work correctly with WPML (the sitepress-multilingual-cms base plugin). This skill orients you — the mental model, how to detect WPML and its add-ons, and which of the three compatibility mechanisms to reach for. The mechanics of each live in dedicated skills (wpml-config, wpml-language-api, wpml-string-translation).

Mental model — WPML translates COPIES

The single most important thing to internalise: WPML creates a separate post/term for each language. A page in English (ID 10) and its Hungarian translation (ID 42) are two distinct WP objects, linked by a shared trid (translation group ID) in the icl_translations table. WPML sets the current language, and WordPress queries return the objects in that language.

This is the opposite of live-translation plugins (e.g. TranslatePress) that translate one page's output on the fly. Consequences for your code:

• To display "the translation of object X in the current language", resolve the translated ID with wpml_object_id — never assume ID 10 is valid in every language.
• IDs, permalinks, and menu items are per-language. Don't cache an absolute URL or an object ID across a request that may switch language.
• Free-form strings your plugin outputs (option values, labels not in a .po file) aren't "copied" — they must be registered for translation (String Translation).

Detecting WPML and its add-ons

WPML is not one plugin — the base handles languages and content copies (and bundles the Translation Management workflow); separately-installed add-ons add string/option translation (String Translation) and media (Media Translation).