Skip to content

Fix WPML compatibility for the gallery block and category transformations - #1376

Open
gabrielcld2 wants to merge 4 commits into
developfrom
fix/wpml-gallery-and-term-transformations
Open

gabrielcld2 wants to merge 4 commits into
developfrom
fix/wpml-gallery-and-term-transformations

Conversation

@gabrielcld2

@gabrielcld2 gabrielcld2 commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes the three WPML compatibility issues reported by the WPML compatibility team (tested with WPML 5.3.0 and WPML Media Translation).

Approach

1. The Cloudinary Gallery block shows the original-language images on translated pages

  • The block stores each image's attachmentId and publicId in its attributes. When the post was rendered, these were used as they are, so a translated page delivered the original-language image. This happened even when WPML Media Translation gave that page a different file.
  • Gallery::prepare_block_render() now runs each image through the existing cloudinary_contextualized_post_id filter. The WPML integration already hooks this filter to return the attachment for the current language.
  • If that attachment can be delivered from Cloudinary, the gallery uses its ID and public ID. This uses the same rule as the rest of the delivery (Media::cloudinary_id()): only a missing required sync item, such as the file, blocks it, and a pending sync gets queued. The stored transformations of the original are dropped, so they get rebuilt for the new attachment.
  • Otherwise the stored image is kept: when there is no translation (WPML returns null), or when the translation can't be delivered from Cloudinary yet.

2. A category's image transformation doesn't apply to translated posts

  • Category transformations are stored as the cloudinary_transformations_image_freeform and cloudinary_transformations_video_freeform term meta. Without a wpml-config.xml, WPML never copied them to translated categories.
  • A new wpml-config.xml at the plugin root declares both fields as copy. WPML then copies them when a category translation is created, and syncs them when the original category is saved.
  • The term transformations are now saved on edit_{$taxonomy} instead of edited_{$taxonomy}. That runs before edited_term and saved_term, so WPML copies the new values on the same save, whichever of those hooks it syncs term meta on.
  • It also declares two post meta as copy, so a post's "Cloudinary terms transformations" settings carry over to its translations:
    • cloudinary_apply_type_terms, the "Disable Cloudinary global transformations" option.
    • cloudinary_transformations_terms, the order the term transformations are applied in. It stores term IDs of the original post's language, so Global_Transformations::get_terms() now runs each stored term through a new cloudinary_contextualized_term filter. The WPML integration maps it to its translation in the post's language.
  • wpml-config.xml is added to the copy:dist list in gruntfile.js so it ships in the release ZIP.
  • Existing sites: categories translated before this change get the transformation when their original category is saved again.

3. The featured image's "Overwrite Global Transformations" setting doesn't apply to translated posts

  • The setting is stored as the _cloudinary_featured_overwrite post meta, which WPML didn't copy to translations. wpml-config.xml now declares it as copy.
  • That covers the classic editor, which saves it on save_post before WPML copies the fields. It isn't enough for the block editor: WPML only copies post meta that changed before its own save_post handler, and the block editor saves this meta through the REST API after that, so it was never copied.
  • The WPML integration now calls WPML's wpml_sync_custom_field when this meta is added, updated or deleted on an original-language post. Changes on a translation aren't pushed (translations get their original's value), and a guard skips the meta writes WPML makes while syncing.

Changelog note

  • Suggested entry: "Improved WPML compatibility: the Cloudinary Gallery block now shows translated images, and category transformations, post term transformation settings and the featured image "Overwrite Global Transformations" setting now apply to translations. Translations created before this version get their category transformations once the original category is saved again."

Out of scope

  • On sites where WPML handles media automatically, translated posts can reference an original-language attachment that has no translation. Those images are served by WordPress rather than Cloudinary on translated pages. That's existing behaviour and isn't changed here.

QA notes

  • npm run test:unit -- --filter Test_Gallery_Contextualize_Asset covers the gallery swap:
    • A synced translation is used, and the rendered gallery gets its own transformations, not the original's.
    • The stored image is kept when there is no contextualization, when there is no translation, or when the translation isn't synced.
    • A translation that can't be delivered from Cloudinary yet keeps the stored image.
  • npm run test:unit -- --filter Test_Global_Transformations_Terms covers the term transformations: saved on edit_{$taxonomy}, and the stored ordering contextualized through cloudinary_contextualized_term in its stored order.
  • npm run test:unit -- --filter Test_WPML_Sync_Post_Meta covers the featured image setting sync: changes and deletions on an original are synced, while changes on a translation, other meta keys and writes made during the sync are not.
  • Manual check, with WPML, WPML Media Translation and WPML String Translation active. English is the default language and French is the second language.

Issue 1: the Cloudinary Gallery block uses translated images

Note: the Gallery block's preview in the editor won't load until #1368 is merged. This doesn't affect the front end.

  1. Media → Add New: upload image A.
  2. WPML → Translations → Media tab: click the + in the French column for image A and upload a clearly different image B as the French file. Save.
  3. Switch the admin language to French. Open Media → Library in list mode (not grid) and check that the French version of A shows as synced in the Cloudinary column.
  4. Posts → Add New (English): add a Cloudinary Gallery block with image A, plus a core Image block with image A for comparison. Publish.
  5. Posts list: click the + in the French column for that post. On the translation screen, click Save and complete.
  6. View the French post (?lang=fr).
    • Expected: the Image block and the Gallery both show image B, served from res.cloudinary.com.
    • Before the fix: the Gallery showed image A.
    • The English post still shows image A in both blocks.

Issue 2: category transformations apply to translated posts

  1. Posts → Categories (English): create a category. Under Cloudinary Category transformations → Category Image transformations, enter e_grayscale. Save.
  2. WPML → Translations → Taxonomy tab: add the French translation of the category.
  3. Go back to Posts → Categories and click the French filter above the list. Edit the new French category and check that the e_grayscale transformation was copied over.
  4. Posts → Add New (English): add a core Image block with an image that has a French version (image A from issue 1 works). Assign the category and publish.
  5. Posts list: click the + in the French column for that post, then Save and complete on the translation screen.
  6. View the French post.
    • Expected: the image is served from res.cloudinary.com with e_grayscale in its URL.
    • Before the fix: the URL had no transformation.
  7. Optional: change the English category's transformation to e_sepia and save. The French post's image should switch to sepia.
  8. Edit the English post. In the Cloudinary terms transformations box, tick Disable Cloudinary global transformations and update the post. Then update the French translation (posts list → pencil icon in the French column → Save and complete).
    • Expected: the French post's image URL has the same transformations as the English one, with no global image transformations added.
    • Before the fix: the option wasn't copied, so the French image also got the global transformations.
  9. Edit the English category's transformation once more (e.g. back to e_grayscale) and save once. Edit the French category: the new value should already be there, without saving the English category a second time.

Issue 3: the featured image's "Overwrite Global Transformations" setting applies to translated posts

  1. Create an English post with a featured image that has a French version (image A from issue 1 works) and publish it. Create the French translation (posts list → + for French → Save and complete).
  2. View the French post and inspect the featured image: its data-transformations attribute (or the delivered URL) contains the global transformations, e.g. f_auto,q_auto.
  3. Block editor: edit the English post, tick Overwrite Global Transformations under the featured image, and save once.
    • Expected: on the French post, the featured image no longer has the global transformations (empty data-transformations).
    • Before the fix: the French post kept the global transformations.
  4. Untick it and save once: the global transformations come back on the French post.
  5. Classic editor (optional, with the Classic Editor plugin): repeat steps 3–4. The result should be the same.

…ions

- The Cloudinary Gallery block now delivers the translated attachment for the
  current language, through the cloudinary_contextualized_post_id filter, when
  that attachment is synced. It keeps the stored asset otherwise.
- Add a wpml-config.xml so WPML copies the category image and video
  transformation term meta to translated terms, and ship it in the build.
- Only swap a gallery asset for its contextualized attachment once that
  attachment is fully synced, and queue it for sync otherwise when auto sync
  is enabled, like attachments found in the post content.
- Copy the "Disable Cloudinary global transformations" post option to
  translated posts through wpml-config.xml.
- Cover the swap at render level, including the rebuilt transformations.

@utkarshcloudinary utkarshcloudinary left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left one blocker and some nits; otherwise this looks good!

Comment thread wpml-config.xml
Comment on lines +6 to +7
<custom-term-field action="copy">cloudinary_transformations_image_freeform</custom-term-field>
<custom-term-field action="copy">cloudinary_transformations_video_freeform</custom-term-field>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

blocker: The term meta copy runs one save behind on edit.

WPML hooks SitePress::create_term on edit_term (priority 1). That calls WPML_Term_Actions::save_term_actions(), which adds sync_term_meta on the generic edited_term hook. sync_term_meta copies the original term meta to the translations.

Cloudinary saves this meta on edited_{$taxonomy} (class-global-transformations.php L718). In wp_update_term(), edited_term fires before edited_{$taxonomy}. So WPML copies the old freeform value, and then Cloudinary writes the new value on the original only. The translated term gets the new value only on the next save of the original.

Create is not affected: create_{$taxonomy} fires before created_term.

Suggested fix: in Integrations\WPML, hook edited_{$taxonomy} at a priority later than 10 and run ( new \WPML_Sync_Term_Meta_Action( $sitepress, $tt_id ) )->run() again. Another option: save the Cloudinary term meta on edit_term at priority 0 instead of edited_{$taxonomy}.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for digging into this! I couldn't reproduce it on the WPML version in our local env (5.0.0-pre.1): there, WPML_Term_Actions::save_term_actions() hooks sync_term_meta on saved_{$taxonomy} at PHP_INT_MAX, which runs after our save, and a single save of the original through the edit form copied the new value to the translation. That may differ in other WPML versions, so I went with your second suggestion: the term meta is now saved on edit_{$taxonomy}, which fires before both edited_term and saved_term. It works whichever hook WPML uses, and doesn't depend on WPML internals. Done in 1318792, with a unit test on the hook.

Comment thread php/media/class-gallery.php Outdated
}

$sync = $this->media->sync;
if ( ! $sync->is_synced( $contextualized_id ) ) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

warning: is_synced() is stricter than the normal delivery path.

is_synced() needs a full signature match. Media::cloudinary_id() (class-media.php L1790-1799) falls back to the local URL only when the missing sync type is required (for example file). When only a non-required item is stale (meta, breakpoints, delivery), it still delivers from Cloudinary.

So with this check, a translated attachment that has a valid public ID and only a stale non-required signature item keeps the original-language asset in the gallery. Core image blocks on the same page deliver the translated asset.

Suggested fix: use the same rule as cloudinary_id(). Swap when has_public_id() is true and is_required( maybe_prepare_sync( $id ), $id ) is false. Another option: swap when $this->media->cloudinary_id( $contextualized_id ) is not false.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. The gallery now uses Media::cloudinary_id(), so it follows the exact rule the rest of the delivery uses: it swaps unless a required sync item is missing. Done in 1318792.

Comment thread php/media/class-gallery.php Outdated
Comment on lines +583 to +585
if ( $sync->is_auto_sync_enabled() ) {
$sync->add_to_sync( $contextualized_id );
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: This runs on each front-end render. add_to_sync() calls set_pending(), which is an update_post_meta() write. For a translated attachment that stays unsynced (sync error, or not uploadable), each page view writes post meta for each gallery item.

Delivery does the same, so this matches existing behavior. A ! $sync->is_pending( $contextualized_id ) guard before add_to_sync() removes the repeated writes.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is covered by the switch to cloudinary_id(): it queues through maybe_prepare_sync(), and can_sync() returns false while the attachment is pending, so there are no repeated writes. That's the same as Delivery.

Comment thread wpml-config.xml
Comment on lines +2 to +4
<custom-fields>
<custom-field action="copy">cloudinary_apply_type_terms</custom-field>
</custom-fields>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

warning: cloudinary_transformations_terms (the term order post meta) is not declared.

If WPML does not copy it, the translated post falls back to wp_get_object_terms() order in Global_Transformations::get_terms(). The freeform values are joined in that order (L277), so the translation can apply the term transformations in a different order than the original. cloudinary_apply_type_terms is copied, so the two settings can disagree on the translation.

If it is copied as is, the stored values (category:12) are source-language term IDs.

Suggested fix: declare it explicitly. Either copy it and map each taxonomy:id through wpml_object_id in get_terms(), or set it to ignore and accept the default order on translations.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, the order and the apply type shouldn't disagree. I went with copy plus mapping: get_terms() now passes each stored term through a new cloudinary_contextualized_term filter, and the WPML integration maps it to its translation in the post's language with wpml_object_id. Translations keep the original's order and use their own terms. Done in 1318792, with unit tests.

Comment thread wpml-config.xml
@@ -0,0 +1,9 @@
<wpml-config>
<custom-fields>
<custom-field action="copy">cloudinary_apply_type_terms</custom-field>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: copy applies only when the original is saved. Existing translations stay out of sync until someone saves the original again. A short note in the changelog will help.

Also, the Cloudinary fields stay editable on translations. For posts, WPML save_post_actions (priority 100) runs after save_taxonomy_ordering (priority 10), so an edit to the checkbox on a translation is lost when WPML copies the original value back. Think about disabling or hiding these fields on translations when WPML is active.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added a suggested changelog entry to the PR description, including the "re-save the original category" note, so it can go in at release. You're right that our fields stay editable on translations and the edits get overwritten. Since fixing that touches both the category form and the post metabox, I'd suggest a follow-up ticket rather than adding it here.

Comment thread wpml-config.xml
</custom-fields>
<custom-term-fields>
<custom-term-field action="copy">cloudinary_transformations_image_freeform</custom-term-field>
<custom-term-field action="copy">cloudinary_transformations_video_freeform</custom-term-field>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit (outside the diff): Global_Transformations::__construct() L85-86 reads $this->globals['image']->get_value() twice and never reads the video settings. The video freeform taxonomy field is defined in ui-definitions/settings-video.php, but it probably never registers, so cloudinary_transformations_video_freeform is never written. This entry does no harm. The constructor bug belongs in a follow-up.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked this one: $this->globals['image']->get_value() returns the values of every media setting, video ones included (video_freeform among them), so the video field does register. The category form shows video_settings[video_freeform], and saving it writes cloudinary_transformations_video_freeform (and WPML copies it to the translation). Reading the image settings twice is just redundant, so there's no functional bug. Happy to tidy it in a follow-up.

- Save the term transformations on edit_{$taxonomy}, before edited_term and
  saved_term, so WPML copies the new values to translations on the same save
  regardless of the hook it syncs term meta on.
- Swap a gallery asset for its contextualized attachment using the same rule
  as the rest of the delivery (Media::cloudinary_id()), which also handles
  queueing the sync without repeated writes.
- Copy the term transformations ordering to translated posts, and map its
  terms to the post's language through a new cloudinary_contextualized_term
  filter.

@utkarshcloudinary utkarshcloudinary left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good ✅

- Declare _cloudinary_featured_overwrite as copy in wpml-config.xml, so the
  "Overwrite Global Transformations" flag of a post's featured image applies
  to its translations.
- WPML only copies the post meta that changed before its save_post handler,
  and the block editor saves the flag through the REST API after it. Sync the
  flag through wpml_sync_custom_field when it changes on an original post.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants