Configuration reference

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.

All settings are optional and live below DiploTranslatorOmni. Out-of-range values are normalised to safe effective values and logged as warnings.

Names are relative to each section below. For example, the full configuration path for MaxSectionPages is DiploTranslatorOmni:ContentTranslation:MaxSectionPages. The translation-request settings are directly under DiploTranslatorOmni. Licence keys and approved profile selections are managed in Settings → Translator settings, rather than in this configuration.

Example appsettings.json configuration

This example shows the configurable settings with their current effective defaults. Merge the DiploTranslatorOmni section into your existing appsettings.json, keeping the site's other settings. If that section already exists, update its entries rather than adding a duplicate. You only need to include settings you want to override.

{
  "DiploTranslatorOmni": {
    "ChatProfileAlias": null,
    "TranslationRequestTimeoutSeconds": 60,
    "TranslationRetryCount": 2,
    "TranslationRetryDelayMilliseconds": 500,
    "MaxConcurrentTranslationRequests": 4,
    "MaxConcurrentContentUnitTranslations": 2,
    "MaxConcurrentTranslationJobs": 2,
    "MaxQueuedTranslationJobs": 20,
    "ContentTranslation": {
      "JobHistoryPageSize": 50,
      "MaxSectionPages": 1000,
      "MaxSelectedPages": 1000,
      "MaxSelectedPropertiesPerPage": 100,
      "PropertyEditorMappings": []
    },
    "Glossary": {
      "AllowSectionUsersToManage": true
    },
    "Permissions": {
      "AllowSectionUsersToOverwriteExistingValues": true
    },
    "DatabaseCleanup": {
      "Enabled": true,
      "InitialDelayMinutes": 5,
      "IntervalHours": 24,
      "ContentStateRetentionDays": 0,
      "JobHistoryRetentionDays": 90,
      "BatchSize": 1000
    },
    "Diagnostics": {
      "Enabled": false,
      "IncludeRawValues": false,
      "DevelopmentOnly": true,
      "Path": "App_Data/DiploTranslatorOmni/Diagnostics"
    },
    "Licensing": {
      "RequestTimeoutSeconds": 10
    }
  }
}

Leave ChatProfileAlias as null when using approved profiles in Translator settings; set an alias only for the fallback workflow described below. PropertyEditorMappings is empty by default; see custom editor mapping examples when adding a supported mapping. The fixed paid-licence validation and outage-grace policies are omitted because they cannot be customised. Restart the site after changing concurrency settings.

Translation requests

Setting	Default	Purpose
`ChatProfileAlias`	None	Fallback Chat profile alias, used only when no profiles are approved in Translator settings. Otherwise the approved default applies.
`TranslationRequestTimeoutSeconds`	60	Timeout for each provider attempt; valid range 1–300 seconds. A provider that ignores cancellation may continue after the timeout.
`TranslationRetryCount`	2	Retries after the initial request; range 0–5. Content validation may also request a corrected translation.
`TranslationRetryDelayMilliseconds`	500	Base delay for exponential backoff with jitter; range 0–30,000 ms. Retry delays are capped at 30 seconds.
`MaxConcurrentTranslationRequests`	4	Host-wide request cap, clamped from 1 to 16. Restart required after changing it.
`MaxConcurrentContentUnitTranslations`	2	Range 1–2. Allows the first requests for pairs of independent built-in top-level RichText/TinyMCE fragments to overlap. Set to 1 for serial fragments. Retries, fallbacks, properties, section pages and saves remain sequential. The host-wide request cap and runtime guards still apply. Restart required.
`MaxConcurrentTranslationJobs`	2	Host-wide cap on executing page, section, selected-page batch and Dictionary jobs; range 1–16. Restart required.
`MaxQueuedTranslationJobs`	20	Host-wide capacity for admitted jobs waiting to execute; range 0–1000. Zero disables waiting capacity. A full queue rejects new jobs before evaluation usage is consumed. Restart required.

ContentTranslation

Setting	Default	Purpose
`JobHistoryPageSize`	50	Job-history records requested per page; range 1–500.
`MaxSectionPages`	1000	Maximum pages included in a section scan, including its root; range 1–100,000.
`MaxSelectedPages`	1000	Maximum pages submitted in one section or selected-page batch job; range 1–`MaxSectionPages`.
`MaxSelectedPropertiesPerPage`	100	Maximum selected properties submitted for each page; range 1–1000.
`PropertyEditorMappings`	Empty	Explicit editor-alias mappings to `PlainText` or `RichText`. Up to 200 mappings; see custom property editors for supported value shapes.

Permissions and glossary

Setting	Default	Purpose
`Glossary:AllowSectionUsersToManage`	true	Allows Translation-section users to manage glossary rules.
`Permissions:AllowSectionUsersToOverwriteExistingValues`	true	Allows Translation-section users to use overwrite and force-selected modes.

DatabaseCleanup

Setting	Default	Purpose
`Enabled`	true	Enables scheduled metadata and job-history cleanup.
`InitialDelayMinutes`	5	Delay before the first cleanup run; range 0–10,080 minutes.
`IntervalHours`	24	Interval between cleanup runs; range 1–8760 hours.
`ContentStateRetentionDays`	0	Translation-state retention; range 0–36,500 days. Zero disables age-based cleanup for this table. Removing baselines can cause later comparisons to require review.
`JobHistoryRetentionDays`	90	Completed job-history retention; zero disables cleanup for this table. Range 0–36,500 days.
`BatchSize`	1000	Maximum records processed in a cleanup batch; range 1–2000.

Cleanup never changes Umbraco content values.

Diagnostics

Setting	Default	Purpose
`Enabled`	false	Enables content-translation diagnostic files.
`IncludeRawValues`	false	Includes potentially sensitive raw persisted values.
`DevelopmentOnly`	true	Restricts diagnostic capture to Development.
`Path`	`App_Data/DiploTranslatorOmni/Diagnostics`	Optional output directory; invalid paths fall back to the default.

Follow the diagnostic logging guide for application log levels and file collection. The raw-value flag can expose source and target content; leave it off for routine support details.

Licensing

Setting	Default	Purpose
`RequestTimeoutSeconds`	10	Timeout for Polar licensing requests; range 1–60 seconds.
`PaidValidationIntervalMinutes`	15	Fixed vendor policy for paid validation checks. Overrides are normalised back to 15.
`PaidOutageGraceHours`	24	Fixed vendor policy for eligible previously validated paid licences during temporary provider outages. Overrides are normalised back to 24; this does not extend expired or revoked licences.

These keys belong under DiploTranslatorOmni:Licensing. Activate and manage keys in the backoffice licensing panel. See licence setup.