When you translate a WordPress post with TranslateSense, some Gutenberg blocks may become invalid or display content that does not match the expected translated markup. This can happen when a block’s saved HTML, parsed attributes, registered default values, or current implementation are inconsistent.
This guide explains how Gutenberg stores block content, why default values can contribute to translation-related issues, and how to identify blocks that may need recovery.
Why can Gutenberg blocks become invalid after translation?
A Gutenberg block is reconstructed using its saved content and registered block definition. For a static block, Gutenberg uses the block’s attributes and save implementation to generate HTML, then checks whether that HTML is consistent with the saved markup.
If the translated markup differs from the markup generated by the block, Gutenberg may mark the block as invalid. This does not necessarily mean the translation itself is incorrect. The issue may be caused by how the block stores, reads, or renders its content.
1. Translatable content is supplied by a default value
A block can register an attribute with a default value. If the saved post does not contain an explicit value for that attribute, Gutenberg may use the registered default when reconstructing the block.
For example, a custom block might define the following attribute:
attributes: {
title: {
type: 'string',
default: 'Our Services'
}
}
Suppose the source block displays “Our Services,” but its saved content does not explicitly store a title attribute. The title may be supplied by the block’s registered default instead.
After translation, the saved HTML might contain “Nuestros servicios.” If the block’s current attributes and save implementation still generate “Our Services,” the generated markup may no longer match the translated markup. Gutenberg can then report an invalid block.
This example illustrates one possible cause, not a universal behavior. The actual result depends on the block’s attribute schema, attribute sources, saved content, and save implementation.
2. The block reads content from a different HTML element
Some attributes use a selector and source definition to extract values from the block’s saved HTML. For example, a title attribute might read text from an h2 element. If the saved structure changes or the translated text is placed somewhere else, the attribute may not contain the expected value.
Review the block’s attribute definitions and confirm that its saved HTML contains the elements and attributes expected by those definitions.
3. The block implementation has changed
A block plugin or theme update can change an attribute definition, default value, selector, or save implementation. Older posts may then contain markup that does not match the current implementation. Translation may expose this mismatch, but the underlying cause can be a compatibility change rather than the translation itself.
Understand how Gutenberg stores block values
Understanding where a block stores its values helps you identify why a translated block may become invalid.
- Comment-delimiter attributes: Attributes without a
sourceare generally serialized in the block’s opening comment when their values need to be saved. - HTML-sourced attributes: Attributes using sources such as
text,html, orattributeare read from the block’s saved HTML. - Default values: A registered default is used when an attribute value is not supplied by the saved content.
- Dynamic blocks: Some blocks generate their frontend output dynamically and do not save their rendered HTML in the post content.
For more information, see the official WordPress documentation on Block Attributes and Edit and Save.
How to identify a block that needs recovery
Step 1: Open the translated post
- Open the WordPress dashboard.
- Navigate to the translated post or page.
- Select Edit to open the Gutenberg editor.
- Wait for the editor and the plugins that register the post’s blocks to finish loading.
Step 2: Review the recovery scan
If recovery is pending for the translated post, TranslateSense can scan the editor content for supported block issues. Review the prompt and the blocks reported by the scan.
If you dismissed the initial prompt, open the TranslateSense recovery panel and use the manual scan or recovery action available in your installed version.
Screenshot to add: [TranslateSense recovery prompt with detected blocks]
Step 3: Identify the likely cause
- Check whether Gutenberg explicitly reports the block as invalid.
- Look for unexpected or missing translated text.
- Determine whether the affected content comes from an attribute, saved HTML, or a registered default.
- Check whether the plugin or theme providing the block is active and compatible with the content.
- If you develop the block, inspect its registered attribute schema and save implementation.
What should you do next?
When TranslateSense provides a suitable repair candidate, follow Apply Repairs and Prevent Gutenberg Block Issues to review the proposed changes, apply supported repairs, and verify the results.
If the issue repeatedly affects the same block type, investigate its attribute definitions and saved content before translating additional posts. Correcting the underlying block implementation or content storage may prevent the same problem from recurring.