Configure Umbraco.AI

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.

Omni uses Umbraco.AI to send translation requests to your chosen AI provider. This guide follows on from Installation & configuration and applies to both Umbraco 17 and 18.

What you are setting up

• Provider integration: the NuGet package that connects Umbraco.AI to a service such as OpenAI.
• Connection: the provider credentials and connection settings managed in Umbraco.AI.
• Chat profile: a reusable choice of connection, model and request settings.
• Omni profile settings: the administrator’s list of approved Chat profiles and the default used for translation jobs.

If your site already has a working provider connection and suitable Chat profiles, you can reuse them and go straight to approving profiles in Omni.

1. Install a chat provider

With Omni installed, add at least one provider integration that supports Chat. Use provider packages matching your Umbraco major version: 17.x for Umbraco 17, or 18.x for Umbraco 18. Check each provider’s compatible releases rather than assuming every provider is available for both versions.

For example, to use OpenAI, run the appropriate command in your Umbraco web project:

Umbraco 17

dotnet add package Umbraco.AI.OpenAI --version "17.*"

Umbraco 18

dotnet add package Umbraco.AI.OpenAI --version "18.*"

You can specify an exact compatible release instead. Rebuild and restart the website, then sign in to the backoffice. The AI section should be available; if it is missing, check your user group’s section access. Umbraco’s installation guide covers the core package, provider integrations and access. Select the documentation version matching your site.

Available Chat providers

The Umbraco.AI provider list currently includes the following integrations. All support Chat, the capability Omni uses for translation; additional capabilities vary by provider.

Marketplace quick links

• Umbraco.AI — the core package, installed automatically with Omni.
• Official Umbraco AI packages — filter by your Umbraco version.

2. Connect your provider account

Create an API credential with your chosen provider and enable billing or credits as required. OpenAI users can start with OpenAI API keys. Follow your provider’s account and credential instructions for other services.

1. Open AI → Connections in the Umbraco backoffice and create a connection.
2. Select the installed provider and give the connection a descriptive name and stable alias.
3. Supply the required credentials and any provider-specific endpoint or account settings, then save.

Use the official connection guide for the exact fields. For production, use Umbraco.AI’s configuration references to read credentials from protected application configuration where supported. Keep secrets out of source control, browser-delivered settings and support requests.

Credentials belong to Umbraco.AI and its provider integration. Omni uses the configured connection through a Chat profile and does not manage provider API keys itself.

3. Create one or more Chat profiles

1. Open AI → Profiles and create a profile with the Chat capability.
2. Choose the provider connection and an available model.
3. Give it a clear name and alias, such as translation-everyday or translation-quality, then save.
4. Test its connection and model with representative content before approving it for translators.

You can create multiple profiles using different models, connections or providers. For example, use a lower-cost profile for everyday drafts and another tested profile for more demanding content. See Umbraco’s profile guide for the available settings.

• Start with the model’s default settings. Only set temperature or other controls when the chosen model and provider support them; a low temperature can help consistency where available.
• Allow enough output tokens for your longest text values. For reasoning models, check how reasoning uses the token budget and affects billed usage.
• Test every target language, including rich text, links, placeholders and product terminology.
• Check that profile instructions, contexts and guardrails suit translation and do not reject normal editorial content.

Omni supplies translation instructions with each request. An additional system prompt is optional; avoid competing instructions such as “summarise” or “write marketing copy”. See AI profiles & prompts for an example.

Choosing a model

Lower-cost models can perform very well for everyday website translation, even with minimal reasoning. Models such as OpenAI’s GPT Luna and Anthropic’s Claude Sonnet are useful starting points to compare with your own content. You do not usually need the most expensive model or a high reasoning budget to produce a good translation draft.

Where your model and provider expose reasoning or effort controls, start with a low setting and increase it only if your tests show a useful improvement. Setting names vary: “minimal” is not available on every model. Choose an available model in your Chat profile and compare quality, speed and cost using the same source content and target languages.

Check the current OpenAI model catalogue or Claude model overview for availability, supported settings and pricing. Provider availability and pricing can change.

For specialist or high-value content, compare terminology, nuance and markup preservation with a profile that performs better in your own tests. Have fluent editors review the results. Measure actual usage, retries and review time before estimating the cost of a whole site; the lowest token price does not always give the lowest overall cost.

4. Choose which profiles translators can use

An administrator controls Omni’s approved profiles independently of Umbraco.AI’s profile catalogue. Creating a profile in Umbraco.AI does not automatically add it to Omni’s approved list.

1. Sign in as an administrator and open Settings → Translator settings.
2. Select one or more live Umbraco.AI Chat profiles that translators may use.
3. Choose a default from those approved profiles. A default is required when you enable profile selection.
4. Save the AI profile settings.

Umbraco backoffice

Enlarge ↗

×

Administrators approve the Chat profiles available to translators and choose the default.

Editors can choose an approved profile for a page, section or Dictionary translation job. The selection applies to the whole job; if no profile is chosen, Omni uses its administrator-selected default. Editors cannot select an unapproved profile.

If you do not enable profile selection

When no profiles are approved in Translator settings, Omni does not show a profile selector. It uses DiploTranslatorOmni:ChatProfileAlias if configured; otherwise it uses Umbraco.AI’s default Chat profile. A configured alias must resolve to a usable Chat profile.

The approved list and Omni default take precedence over these fallbacks. If the approved default is deleted or ceases to be a Chat profile, jobs using that default cannot start until an administrator repairs the selection; Omni does not silently switch to the configuration alias or another model. See AI profiles & prompts for the complete selection rules.

5. Check the setup with a small translation

1. Save a source-language page containing representative text.
2. Open Translate, choose the target language and, when available, an approved Chat profile.
3. Preview the selected properties and run a single-page translation.
4. Review the target-language draft for accuracy, terminology and preserved formatting.
5. Check the provider’s usage report before enabling larger jobs.

Page translations remain drafts for editorial review and manual publishing. Dictionary translations save values directly because Dictionary items have no draft/publishing stage.

Common setup problems

• No provider is listed: the core dependency alone is not enough. Install a Chat-capable provider integration, rebuild and restart.
• No usable Chat profile: create a Chat profile with a working connection and model, then approve it and choose an Omni default or configure a valid fallback.
• A provider request fails: check credentials, account billing, model access, quotas and supported profile settings. After an upgrade, verify the connection credentials again.
• An approved profile is unavailable: check whether it was deleted or changed, then update the allowed profiles and default in Translator settings.

See Troubleshooting for more diagnostics and Installation & configuration for languages, permissions and production limits.

Before giving editors access

• Set provider budgets or alerts and review the provider’s data-handling terms for the content you plan to translate.
• Approve only tested Chat profiles and keep human review and normal publishing permissions in place.
• Choose concurrency and page limits appropriate for the provider and host, using the configuration reference.
• Record the provider, model and profile used for testing, and repeat a small acceptance test after changing them.