Cornerstone WPML Safe Migration

A small WordPress MU plugin that adds safe WP-CLI commands for migrating Cornerstone content storage on multilingual WPML sites.

The default Cornerstone HTML Storage migration can be unsafe on WPML sites. During bulk rendering, Cornerstone can reuse the wrong language context or cached document state. That can cause a translated post to receive HTML generated from its source-language post.

This can be hard to catch because the frontend may still render correctly from _cornerstone_data, while raw post_content in the database is wrong. Raw post_content is still used by Classic Editor, search, SEO tools, indexing, exports, and other integrations.

Example failure pattern:

• Each translated post should store Cornerstone HTML whose first marker belongs to that same translated post.
• The source-language post should store HTML whose first marker belongs to the source post.
• In an unsafe migration, Cornerstone can accidentally render the source-language document while saving into a translated post.
• The translated post then receives HTML with the source post's marker, such as e<source-post-id>-e..., instead of its own marker, such as e<translated-post-id>-e....
• The frontend may still look correct because Cornerstone can rebuild from _cornerstone_data, but tools that read raw post_content see content from the wrong post or language.

• Switches WPML to the post's language before rendering.
• Clears Cornerstone resolver and frontend content caches before each render.
• Renders HTML for the exact post ID being migrated.
• Validates the generated HTML before and after saving.
• Refuses to save if the first e<ID>-e marker does not match the post ID.
• Provides validation and repair commands for already-migrated HTML storage.
• Leaves _cornerstone_data unchanged.

Install the plugin as an MU plugin:

wp-content/mu-plugins/cornerstone-storage-safe-migration.php

Then run the WP-CLI commands from the WordPress root.

Preview what would be migrated:

wp cs-safe-migrate --dry-run

Validate current HTML storage and confirm that markers match post IDs:

wp cs-safe-migrate --validate-html

Migrate Cornerstone content from shortcode storage to HTML storage:

wp cs-safe-migrate --limit=500 --offset=0

Migrate one post only:

wp cs-safe-migrate --post=54849

Repair previously migrated HTML storage:

wp cs-safe-migrate --repair-html

Repair one post only:

wp cs-safe-migrate --repair-html --post=54849

Migrate HTML storage back to shortcode storage:

wp cs-safe-migrate --to-shortcode --limit=500 --offset=0

Do not run the migration in production without a database backup.

wp db export /root/cs-safe-migrate-backups/full-db-before-cs-safe-migrate.sql --add-drop-table
wp cs-safe-migrate --dry-run
wp cs-safe-migrate --validate-html
wp maintenance-mode activate
wp cs-safe-migrate --limit=500 --offset=0
wp cs-safe-migrate --validate-html
wp cs-safe-migrate --dry-run
wp maintenance-mode deactivate

After a successful migration, dry run should report:

Will migrate: 0

Validation should report:

Issues found: 0

If production validation fails and you need a full rollback, import the database backup created before the run:

wp db import /root/cs-safe-migrate-backups/full-db-before-cs-safe-migrate.sql
wp cache flush

For a smaller rollback, run --to-shortcode against the affected post or batch after confirming the affected scope.

• The plugin does not modify _cornerstone_data.
• HTML migration uses a narrow raw update of post_content only after generated HTML passes validation.
• If validation fails, the plugin refuses to save the generated HTML.
• Empty Cornerstone documents with _cornerstone_data = [] may generate HTML without an element marker and are treated as valid empty documents.
• Drafts or test pages that fail validation should be inspected individually or deleted if they are no longer needed.
• The admin notice warns editors not to use Cornerstone's default HTML Storage migration on WPML sites.

• WordPress with WP-CLI
• Cornerstone / Pro theme
• WPML for multilingual sites
• Permission to run WP-CLI commands on the server

GPLv2 or later.