Installation & configuration

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.

Install Omni

Omni supports Umbraco 17 and 18 on .NET 10 through the same NuGet package, Diplo.Translator.Omni. Use the 17.x.x version line for Umbraco 17 or 18.x.x for Umbraco 18. Both have identical functionality and configuration, with the same price, licensing and evaluation terms.

Target	Production package	Version line
Umbraco 17	`Diplo.Translator.Omni`	`17.x.x`
Umbraco 18	`Diplo.Translator.Omni`	`18.x.x`

Run the matching command in your Umbraco web project:

Umbraco 17

dotnet add package Diplo.Translator.Omni --version "17.*"

Umbraco 18

dotnet add package Diplo.Translator.Omni --version "18.*"

These commands select the latest stable release within the specified major version. You can also specify an exact release from that version line. Keep Omni on the version line matching your Umbraco major version when updating.

NuGet installs the core Umbraco.AI package automatically as an Omni dependency. Provider integrations are installed separately. Use matching Umbraco.AI and chat provider packages: 17.x for Umbraco 17, or 18.x for Umbraco 18. Rebuild and restart the site after installation. The workflows and settings documented here apply to both Omni version lines.

The current package dependency floors are Umbraco 17.6.1 with Umbraco.AI 17.3.0 for the 17.x line, and Umbraco 18.2.0 with Umbraco.AI 18.3.5 for the 18.x line. Check the selected release's NuGet dependencies when updating; provider packages must also be compatible with that host and AI version.

Restart the application after installation. Omni registers its Management API, background services, Translation-section dashboards and backoffice assets automatically.

Connect an AI provider

Umbraco.AI is installed automatically as an Omni dependency. You still need a separate Chat-capable provider integration and a configured connection and Chat profile. If suitable connections and profiles already exist, reuse them.

Install a compatible provider integration: 17.x for Umbraco 17 or 18.x for Umbraco 18.
Rebuild and restart the site, then configure the provider credentials under AI → Connections.
Create one or more Chat profiles under AI → Profiles, selecting the connection and model for each.
As an administrator, open Settings → Translator settings, approve the profiles translators may use, choose a default from that list and save.
Test a small translation and review the saved draft and provider usage before enabling larger jobs.

Editors can select an approved profile for each page, section or Dictionary job; the selection applies to the whole job. If they make no selection, Omni uses its approved default.

Follow Configure Umbraco.AI for provider commands, connections, credentials, multiple profiles and guidance on testing efficient models with low reasoning effort.

Activate your licence

Obtain a paid or evaluation licence through pricing and evaluation. Retrieve your key from the Polar customer portal using the email address from checkout.
Sign in to Umbraco as an administrator and open Settings → Translator settings.
Enter the key in the licensing panel, activate it and confirm that the expected plan is active.

The free evaluation permits five accepted single-page draft translation runs on one installation, with no time limit. Previews and read-only dashboards do not consume a run. Section and selected-page batch jobs, Dictionary translation, overwriting existing values and forced retranslation require a paid licence. An accepted evaluation run counts even if later translation work fails or is cancelled.

A paid licence covers one production site and up to three active associated installations across development, test, staging and production. Deactivating an installation releases its activation without deleting content or resetting evaluation usage. Keep licence keys private and use the production package for real paid or evaluation keys.

If licensing reports an unknown outcome or reconciliation is required, check the licensing panel and contact support before retrying. See licensing troubleshooting.

Upgrading from Umbraco 17 to 18

When upgrading the host site, update Diplo.Translator.Omni from the 17.x.x version line to 18.x.x and update Umbraco.AI and its provider packages to compatible 18.x releases. The Omni configuration and licensing are the same for both versions. Back up the site and database, follow the Umbraco and Umbraco.AI upgrade instructions, and test the upgraded site before deploying to production. Verify provider connections, credentials and chat profiles, then run a representative translation.

Add package settings

Omni can use its default application settings without an appsettings.json entry. Choose approved profiles and a default in Translator settings first; you do not need ChatProfileAlias for that workflow. To customise request limits or permissions, add optional settings below DiploTranslatorOmni. A practical starting point is:

{
  "DiploTranslatorOmni": {
    "TranslationRequestTimeoutSeconds": 60,
    "TranslationRetryCount": 2,
    "TranslationRetryDelayMilliseconds": 500,
    "MaxConcurrentTranslationRequests": 4,
    "MaxConcurrentContentUnitTranslations": 2,
    "MaxConcurrentTranslationJobs": 2,
    "MaxQueuedTranslationJobs": 20,
    "ContentTranslation": {
      "MaxSectionPages": 1000,
      "MaxSelectedPages": 1000,
      "MaxSelectedPropertiesPerPage": 100
    },
    "Glossary": { "AllowSectionUsersToManage": true },
    "Permissions": { "AllowSectionUsersToOverwriteExistingValues": true }
  }
}

If no profiles are approved in Translator settings, Omni uses the optional ChatProfileAlias when configured; otherwise it uses Umbraco.AI’s default Chat profile. The approved list and Omni default take precedence. If an approved default becomes unavailable, repair it in Translator settings; Omni does not silently fall back to another profile. See AI profiles & prompts for the selection rules.

Configure languages and access

Add at least two languages in Umbraco. Grant trusted translator groups access to the built-in Translation section and the normal browse/update permissions required for their content.

Production checklist

Confirm the correct licence is active and the site's Umbraco version matches the installed Omni and Umbraco.AI packages.
Test each approved profile’s translation quality, prompts, supported model settings, token limits and provider guardrails.
Set provider billing, budgets or alerts, plus concurrency and page limits appropriate for the host and AI provider.
Decide whether section users may manage glossary rules and overwrite existing translations.
Keep diagnostics raw-value capture disabled unless explicitly required.
Review the complete configuration reference.

Jobs execute inside the application and do not resume after a restart. Use one active application instance for translation work; in a load-balanced deployment, job start, status and cancellation must reach that instance. See background jobs and restarts.