This documentation applies to Omni for Umbraco 17 and 18. Both version lines have the same functionality and configuration. Choose the package version for your Umbraco site.
Start with the message shown in the translation preview or job report. It usually explains whether the issue is a provider failure, a skipped value or a decision that needs editor review.
Collect installation details with the Support dashboard
- In your site's Umbraco backoffice, open Translation → Support.
- Choose Refresh to read the current installation details, then Copy support details.
- Review the text and paste it into the optional technical details area of the contact form. Add what you expected, what happened, the source and target cultures, and the relevant job ID or error message.
The summary includes detected versions and AI components, configured languages, provider/model choices and selected translation settings. Profile names and aliases are excluded unless you opt in. Credentials, licence keys, connection strings, content and prompts are excluded. Review the summary before sharing; copying it does not send anything to support or contact an AI provider.
If clipboard access is unavailable, select and copy the preview text manually. If your installed version has no Support dashboard, supply the Umbraco and Omni versions, provider/model and relevant settings manually. An incomplete lookup is a gap in the collected details, rather than confirmation that the installation is healthy.
No chat provider or usable profile is available
Install a Chat-capable Umbraco.AI provider package compatible with your Umbraco version, rebuild and restart the site, then test its connection and model. Check credentials, model access, billing and provider quotas. Follow Configure Umbraco.AI for the setup steps.
In Translator settings, check that the selected profile is approved and still has the Chat capability. An approved default that has been removed or changed must be repaired; Omni does not silently switch to another model. When no profiles are approved, Omni uses DiploTranslatorOmni:ChatProfileAlias if configured, otherwise Umbraco.AI's default Chat profile. See AI profiles & prompts for the selection rules.
A property is skipped or requires review
Review the preview message. The value may be empty, invariant, unsupported, already populated in the target culture or contain no safe translatable text. Existing target values are skipped by default, but tracked new or changed nested block text can still be eligible. See Supported property editors for editor aliases and custom mappings.
Some properties are deliberately skipped. Content and media pickers store references to other items, rather than text to translate. Omni preserves those references, along with values such as URLs, identifiers, numbers, dates and booleans. This is expected behavior, not a translation failure. If a picked content item needs translation, translate that item separately.
Target-edited values, missing baselines, removed source units and unsafe block structure can require review. Compare the saved source and target before choosing to replace any existing text. If the target changes after planning, Omni skips that write; refresh the preview and inspect the latest draft before trying again.
Recent edits or translations are missing
Save source edits first, then use Refresh in Translate. Omni reads server-side saved content, including drafts, rather than unsaved browser edits. After translation, use Review translation to reload the document and inspect the target culture.
Page and section translations are saved as drafts and do not change the published website until an editor publishes them. Dictionary translations are saved directly and have no draft stage.
A translation completes with warnings
Amber Review suggested messages identify text to inspect, such as retained fragments or other non-blocking concerns. They do not mean the whole job failed. Review the affected text and any page-name fallback before publishing. Red messages identify translation, validation or save failures; warning and error counts are separate.
Placeholder text such as “lorem ipsum”, pseudo-Latin or incoherent test copy may also cause warnings. It may have no reliable meaning to translate, so Omni instructs the model to preserve it rather than invent a meaning. Retained source text can then trigger a review warning. Check the highlighted text: if it is intentional placeholder copy, keeping it may be appropriate; otherwise replace it with meaningful source text, save and translate again. Use representative real copy when assessing translation quality.
A translation job has errors
Open Translation Jobs, inspect the report and note the job ID. Check provider credentials, billing, quotas, timeouts and model-supported settings. Validation failures can also mean returned text did not preserve required placeholders or satisfy glossary rules. Inspect the specific message before retrying; successfully saved drafts may already exist.
For more detail, follow the diagnostic logging guide to enable Omni's content-job diagnostic files, capture detailed application logs and investigate errors in Umbraco's Log Viewer. Review logs before sharing and turn temporary diagnostic capture off afterwards.
A user cannot translate or replace existing text
Confirm the user is an administrator or has access to Umbraco's Translation section. Content preview also requires browse permission, and translation requires update permission for the page and target culture. Administrators can restrict overwrite and forced replacement to administrators through Permissions:AllowSectionUsersToOverwriteExistingValues. See the configuration reference.
A job is rejected or waiting
Check the reported reason. Page and section jobs cannot overlap the same content scope. Wait for the existing job to finish, or cancel it and wait for cancellation to complete before retrying. Jobs can also wait in the host's queue; if the queue is full, retry after an active job completes.
A section scan or selection may exceed ContentTranslation:MaxSectionPages, ContentTranslation:MaxSelectedPages or ContentTranslation:MaxSelectedPropertiesPerPage under DiploTranslatorOmni. Choose a narrower root or adjust the relevant limit deliberately. See the configuration reference for limits.
Licence activation or usage needs attention
Ask an administrator to check the plan and status in Settings → Translator settings. Use a real paid or evaluation key with the production package. Evaluation runs allow single-page drafts only; section and batch jobs, Dictionary translation, overwrite and forced retranslation require a paid licence. Accepted evaluation runs count even if the job later fails or is cancelled, and deactivation does not reset usage.
If activation or evaluation usage has an unknown outcome, do not repeatedly retry it. Check the reconciliation message and contact support with the error and any support admission ID. Resolve a reconciliation item only after its provider outcome has been verified. Never send your key.
A restart interrupts a job
Translation jobs run inside the application and do not resume after a restart, recycle or process failure. Stale persisted jobs are marked failed during startup or maintenance. Inspect the target drafts and refresh the preview before starting another run; already saved drafts remain saved.
For load-balanced sites, job start, status and cancellation must reach the same active application instance. Database overlap checks do not provide a distributed job queue.
Investigating concurrency or SQLite errors
SQLite and SQL Server are supported for Omni's stored data. Disabling Umbraco.AI analytics and audit logging is not a general prerequisite. If logs show database-locking or concurrent-operation errors, capture the exact error and component versions first. To compare behavior with serial provider requests, apply these settings in appsettings.json and restart the site:
{
"DiploTranslatorOmni": {
"MaxConcurrentTranslationRequests": 1,
"MaxConcurrentContentUnitTranslations": 1
}
}The Support dashboard shows configured limits; runtime safety guards can reduce actual concurrency. Share the error and whether it still occurs with serial requests when asking for help.