TranslateSense Gutenberg Block Recovery helps you identify supported issues in translated Gutenberg blocks and apply available repairs in the editor. This guide explains how to use Apply Repairs, verify the result, troubleshoot unresolved blocks, and prevent recurring problems by storing translatable content correctly.
Before applying repairs
Before making changes, make sure the translated post is open in Gutenberg and that the relevant block plugins have finished loading. For important pages, keep a backup or a restorable revision so you can recover the original content if necessary.
- Open the translated post in the Gutenberg editor.
- Allow the editor and relevant block registrations to finish loading.
- Review the affected blocks and the available repair candidates.
- Make sure you can restore the original content if a repair changes the layout unexpectedly.
How to apply repairs to translated Gutenberg blocks
Step 1: Open the translated post
- Open the WordPress dashboard.
- Navigate to the translated post or page that needs attention.
- Select Edit to open the Gutenberg editor.
- Wait for the editor and the relevant block plugins to finish loading.
Step 2: Review the recovery prompt
If recovery is pending, TranslateSense can scan the post and display a recovery prompt when it detects supported issues. Review the affected block types and the available repair information before proceeding.
If you previously dismissed the prompt, open the TranslateSense recovery panel in the editor and use the available manual scan or recovery action.
Screenshot to add: [TranslateSense recovery prompt and affected block list]
Step 3: Review the available repairs
Inspect the proposed repair candidates before applying them. A suitable repair should preserve the translated content and the intended block structure while correcting the inconsistency identified by the recovery workflow.
- Review the affected block type and the issue reported by the recovery scan.
- Check whether TranslateSense provides a repair candidate for the block.
- Pay particular attention to headings, paragraphs, links, images, captions, and other content that must remain intact.
- Do not assume that an invalid block can always be repaired automatically. Some custom and third-party blocks require manual investigation.
Step 4: Select Apply Repairs
- Select Apply Repairs when a suitable repair is available.
- Wait for the repair operation to finish before navigating away from the editor.
- Review the repair results and note any blocks that remain unresolved.
- Inspect the repaired blocks to make sure their translated text, formatting, and structure are correct.
Screenshot to add: [TranslateSense Apply Repairs button and repair progress]
Step 5: Verify and save the post
- Confirm that successfully repaired blocks no longer display invalid-block warnings.
- Check the translated text, links, images, formatting, and overall layout.
- Review unresolved blocks individually instead of assuming they are safe to ignore.
- Save or update the post after verifying the changes.
- Preview the translated page on the frontend to confirm that it renders as expected.
Recovery results should reflect the issues that were actually resolved. If the scan still detects an unresolved issue, investigate it before treating the post as fully recovered.
How to prevent default-value-related block issues
One way to reduce recurring translation issues is to make sure translatable content is stored in the block’s actual content or in an appropriate serialized attribute. Avoid relying on a language-specific default value to supply the text that should appear in a translated post.
This is especially relevant for blocks whose JavaScript registration defines default titles, descriptions, labels, captions, or other text. The correct solution depends on how the block stores its content and generates its saved markup.
Method 1: Enter the actual content in the block editor
If a block is displaying example or default text, use the block’s supported editing controls to enter the actual content before translating the post.
- Open the source post in Gutenberg.
- Select the affected block.
- Locate the title, description, caption, or other field that contains the default text.
- Enter the actual content that should appear on the page.
- Save or update the source post.
- Confirm that the content is saved correctly and that the block remains valid.
- Translate the post with TranslateSense and inspect the translated result.
For example, if a block displays “Our Services” only because that text is supplied by its registration default, enter the intended title through the editor and save it using the block’s supported content mechanism. This can help ensure that the title is represented in the saved content rather than depending solely on the default.
Note that entering a value through the editor does not guarantee that the value will be serialized explicitly if the block’s implementation or Gutenberg serialization rules omit default-valued attributes. If the problem persists, inspect the block’s attribute definition and saved content.
Method 2: Store translatable values in explicit block attributes
For block developers, translatable content should be represented by attributes or saved markup that can consistently preserve the intended value. The attribute definition, editor controls, and save implementation must agree about how the content is stored and restored.
For example, a block can define a title attribute without using a language-specific default:
attributes: {
title: {
type: 'string'
}
}
When the editor assigns a title to this attribute, Gutenberg can serialize the value in the block’s comment delimiter when the attribute does not use an HTML source. The exact result depends on the block implementation and serialization behavior.
For an HTML-sourced attribute, define the appropriate source and selector instead. For example:
attributes: {
title: {
type: 'string',
source: 'text',
selector: 'h2'
}
}
In this example, Gutenberg reads the title from the text content of an h2 element in the saved markup. The block’s save implementation must output that element and its content consistently.
Do not change an existing attribute’s source or type without checking compatibility with previously saved content. Such changes may require a block migration or a deprecation strategy.
Method 3: Avoid language-specific default content
For custom blocks, avoid using language-specific strings as defaults for content that users are expected to author or translate, such as headings, paragraphs, descriptions, and captions. Consider using an appropriate empty default and requiring the content to be supplied through the editor.
For example, instead of defining a title that always defaults to Our Services, the block can use an empty string as its default and render the saved title when one is provided. The block should also handle empty values intentionally.
Defaults remain useful for structural settings such as alignment, layout options, spacing, and display configuration. The goal is not to remove every default, but to avoid relying on a language-specific default as the source of translatable content.
Method 4: Keep the save implementation consistent
For static blocks, the save implementation should generate markup that matches the stored attributes and saved content. If a block changes its markup or attribute schema, older saved content may require a compatibility migration.
- Make sure the save implementation renders the values represented by the block’s attributes.
- Ensure that HTML-sourced attributes use selectors that match the generated markup.
- Test content after changing default values or attribute definitions.
- Use block deprecations or migrations when a new implementation must support older saved content.
- Test both source-language and translated posts before deploying a block update.
For dynamic blocks whose save implementation returns null, frontend output may be generated on the server. In such cases, static saved-HTML comparison alone is not sufficient to diagnose every rendering issue. Inspect the block’s saved attributes and server-side rendering logic as well.
Troubleshooting unresolved blocks
The block is still invalid after Apply Repairs
- Run the available recovery scan again to confirm the current state.
- Check whether the block’s plugin or theme is active and compatible with the saved content.
- Inspect the saved markup, registered attribute definitions, and generated markup to locate the mismatch.
- Check for changes to the block’s save implementation or registered defaults.
- Use manual recovery or contact the block developer if no safe repair is available.
The translated text appears correct, but the block is invalid
Correct visible text does not necessarily mean that the block’s saved markup and attributes are consistent. Check whether the text is read from an HTML selector, supplied by a registered default, or generated from another attribute. The block may require a correction to its content storage or save implementation rather than another translation attempt.
The same issue occurs across multiple translated posts
If the same block type repeatedly becomes invalid across translated posts, investigate the block implementation and attribute schema. Correcting a default-value or serialization issue at its source may prevent the same problem from recurring in future translations.
Summary
TranslateSense Block Recovery helps identify and repair supported issues in translated Gutenberg content. For long-term prevention, ensure that translatable content is stored in the appropriate attributes or saved markup, avoid depending on language-specific default values, and keep the block’s attribute definitions and save implementation consistent.
For more information about block attributes and serialization, see the official WordPress documentation on Block Attributes and Edit and Save.
Screenshot to add: [TranslateSense recovery results showing repaired and unresolved blocks]