Coordinate translated content with cache invalidation

Translated sites can produce different HTML and progressive JSON for the same logical content in different locale paths. Cache keys, generation contexts, and invalidation must preserve that separation.

Built-in POM Translate events

When the progressive JSON master is enabled and the JSON purge-on-translation setting is active, POM Cache listens for:

pom_translate_string_changed
pom_translate_translation_changed
pom_translate_slug_changed

Each event triggers a full current-site progressive JSON purge with the translation_change context. This ensures that translated archive labels, fields, URLs, or slugs are regenerated together.

The setting controls JSON invalidation. It does not imply that every translated HTML artifact or external CDN object has been cleared.

A third-party translation integration

After committing a public translation change, clear the representations it affects:

function my_translation_plugin_public_text_changed() {
    $context = 'my_translation_plugin_change';

    if ( function_exists( 'pom_cache_delete_site_cache' ) ) {
        // Translated navigation and initial markup can affect HTML.
        pom_cache_delete_site_cache( $context );
    }

    if ( function_exists( 'pom_cache_json_delete_site_cache' ) ) {
        // Progressive archive labels and fields can affect JSON.
        pom_cache_json_delete_site_cache( $context );
    }
}

Call this after the translation transaction succeeds, not before and not once per individual string in a bulk translation job.

If your data affects JSON only, omit the HTML clear after proving that no initial page, metadata, navigation, structured data, or fallback text consumes it.

Locale-aware JSON keys

A translated progressive payload must have a deterministic locale-specific relative path. The POM Theme progressive archive context supplies the locale URL prefix used by its cache mapping.

When calling pom_cache_json_purge_context() with post_type and locale, POM Cache can use that same POM Theme context class to target:

[locale-prefix]/archive/[post-type]

If the class is unavailable, no locale prefix is inferred. If post_type is missing, the helper clears all current-site JSON. Validate the context before assuming a targeted purge.

Slug changes

A translated slug change can leave two separate concerns:

• the old cache path may still contain a reusable file;
• the new path needs fresh HTML or JSON;
• Apache and CDN layers may still recognize the old public URL.

Clear the relevant origin stores, verify WordPress rewrite behavior, and invalidate both old and new CDN paths when necessary. Do not rely on a new cache key to make the old public response disappear.

Machine and bulk translation

During bulk translation:

1. keep the current public cache until the translated data reaches a consistent commit point, unless serving it would be incorrect;
2. defer redundant automatic clears with durable job state if required;
3. clear HTML and JSON once per affected site at completion;
4. clear on failure or cancellation before releasing any suppression;
5. regenerate representative locale routes;
6. invalidate the CDN after the origin is correct.

Verification matrix

For every supported language:

• request the same content in its locale-specific URL;
• confirm that the HTML and JSON do not cross languages;
• change a translated string and verify regeneration;
• change a translated slug and test both old and new URLs;
• repeat while logged in to confirm private state remains dynamic;
• verify origin results before the CDN.

The cache is correct only when language variants are isolated and every translation change has a defined invalidation point.