Use this order—do not guess

Troubleshooting is fastest when the storage system, language assignment, inventory, provider, worker, validation and front end are checked in sequence. Starting repeated jobs before identifying the category creates duplicate work and makes logs harder to interpret.

1. Confirm the multilingual system

• Exactly the intended Polylang, WPML or TranslatePress workflow is active.
• Source and target languages are configured.
• The original item is assigned to the source language.
• The target is not accidentally being used as a new original.
• Language URLs and the language switcher work before translation.

2. Content missing from the list

1. Open Translator → Settings and enable the required public post type.
2. Confirm the content is not Trash, auto-draft or a target-language copy.
3. Remove overly narrow Translate filters.
4. Select the correct original language and target language.
5. Choose Rebuild inventory on the Dashboard.

Inventory rebuild is read-only. If a custom post type remains absent, verify that it is public and has a user interface. Technical internal post types should not be forced into translation.

3. Wrong target language

Stop/cancel the queue, then inspect the original item’s language assignment and selected target checkbox. For Polylang/WPML, inspect the target post’s language relationship. Delete only the incorrect target draft after confirming the source ID. Rebuild inventory and run one-item Draft test.

4. Provider test fails

• 401/403: key, permissions, project or account access.
• 429: provider rate limit, quota or billing.
• Timeout/connection: outbound HTTPS, firewall, DNS or provider availability.
• Low quality score: model capability, conflicting instructions, broken glossary or excessive creativity.
• Missing model: choose a stable model available to the account.

5. Job waits in Queued

1. Check WordPress Site Health for scheduled-event and loopback errors.
2. Load another admin page to trigger normal WP-Cron.
3. Confirm security software does not block admin callbacks.
4. Use a real hosting cron on low-traffic sites.
5. Keep the maximum small-run items at one until stable.

6. Retry message or connection error

Wait for the stated retry time. Check provider status and account limits. Completed checkpoints are preserved. Do not cancel and launch duplicates unless the selected item/language was wrong or the job reached a final failure.

7. Failed result

1. Open Jobs & Logs.
2. Expand Technical details.
3. Read the human explanation, error code and processed/expected section counts.
4. Correct the specific provider, worker, language, structure or rendered-string issue.
5. Use the result card’s retry action.
6. Preview the completed result before publishing.

A failed result must not overwrite the original. If target content exists, determine whether it is an older linked draft, a partial target or a valid result saved just before cancellation.

8. Some text remains untranslated

• Check whether it is global theme/plugin text rather than page content.
• Open tabs, variations, forms and popups so dynamic strings render.
• For TranslatePress, inspect missing dictionary strings.
• For Polylang/WPML, use the system’s string-registration workflow for interface strings.
• Check protected terms and glossary rules.
• Confirm the custom field or builder widget is supported and enabled.

9. Layout differs from the source

1. Keep the target as Draft.
2. Compare post type, template, parent, builder metadata and theme conditions.
3. Confirm the correct adapter created the target.
4. Check custom fields, featured image and global template relationships.
5. Regenerate builder CSS only after saved structure is correct.
6. Clear caches and compare desktop, tablet and mobile.

Do not translate CSS, JavaScript, IDs or serialized controls. Do not copy an unrelated theme/template merely because it visually resembles the source.

10. WooCommerce data is wrong

Stop publication. Compare source and target product relationship, type, variations, price, stock, SKU, dimensions, tax, downloads and images. These are technical/synchronized values. Correct the multilingual commerce relationship before retranslating customer-facing text.

11. Menu or homepage is empty

Create/assign the target-language menu through the active multilingual plugin and assign it to the same theme location. Verify the translated front page setting and language switcher. Do not repair a multilingual menu by changing theme CSS.

12. Safe escalation package

• Translator version.
• WordPress, PHP, WooCommerce, builder and multilingual-plugin versions.
• Content ID, source language and target language.
• Job/result ID, timestamp and safe error code.
• Expected result, actual result and exact reproduction steps.
• Whether Site Health cron/loopback and provider test pass.

Never include passwords, full licence keys, API keys or customer-sensitive source content.