Version: 3.x.x

Server configuration

As the Server is based on Spring framework, it follows its configuration standards. You can configure Tolgee by providing a configuration file, provide configuration properties as command line arguments when you run Tolgee with java -jar command, or as environment variables.

Example configuration files:

YAML
.env
application.properties

tolgee:
  authentication:
    enabled: true
    initial-password: admin
    initial-username: admin
    jwt-secret: my_jwt_secret
  machine-translation:
    google:
      api-key: my_google_api_key
  smtp:
    auth: true
    from: Tolgee <no-reply@mydomain.com>
    host: email-smtp.regional-region.amazonaws.com
    password: 'omg/my/password'
    port: 465
    ssl-enabled: true
    username: user@company.com

Server settings

Prefix: server

These properties are used to configure the server.

port

Port on which Tolgee exposes itself. (default: 8080)

Spring settings

Prefix: spring

These properties are used to configure Spring framework.

Data source settings

Prefix: spring.datasource

Since Tolgee is built on Spring framework, you have to edit following configuration props to configure its database connection. These properties can be omitted when using Postgres autostart, which is enabled by default.

url

The url of the datasource in format jdbc:postgresql://host:port/dbname. e.g. jdbc:postgresql://db:5432/postgres
username

Database username. e.g. postgres
password

Database password. e.g. postgres

Tolgee

Prefix: tolgee

Configuration specific to Tolgee.

back-end-url

Public URL of the Tolgee API endpoint. While this typically matches the 'frontEndUrl', it should be set separately when running the backend on a different URL.
file-storage-url

Public base path where files are accessible. Used by the user interface.
front-end-url

Public URL where Tolgee is accessible. Used to generate links to Tolgee (e.g. email confirmation link).

Warning: Not providing this property leads to security issues.Providing this property is highly recommended especially if you are managing publicly accessible Tolgee instance.
max-screenshots-per-key

Maximum amount of screenshots which can be uploaded per API key. (default: 20)
max-translation-text-length

Maximum length of translations. (default: 10000)
max-upload-file-size

Maximum size of uploaded files (in kilobytes). (default: 51200 ≈ 50MB)
translations-view-languages-limit

Maximum amount of languages that can be selected in the Translations view. Set to -1 for no limit. (default: -1)

Asynchronous execution

Prefix: tolgee.async

Sizing of the thread pools Tolgee uses for work that runs outside the HTTP request thread.

By default both are derived from the size of the database connection pool, so a larger instance automatically gets more concurrency without any extra configuration.

warning

Every in-flight streaming response holds one database connection for its entire duration. That is why streaming.max-threads is derived from, and must stay well below, your database connection pool size — together with tolgee.batch.concurrency and the connections ordinary requests need.

Background tasks

Prefix: tolgee.async.background

Thread pool serving background (@Async) work: e-mail sending, analytics reporting, translation statistics recomputation and project hard-deletes. Websocket activity broadcasts and automation triggers run on their own single-threaded pools, so their ordering and debouncing are preserved, and are not affected by this setting.

Its queue is unbounded — background work is queued, never dropped and never run on the thread that submitted it.

keep-alive-seconds

How long an idle background thread is kept alive before it is released, in seconds. (default: 60 1 minute)
max-threads

How many background tasks Tolgee runs in parallel on this instance.

There is no way to switch background processing off: 0 and any negative value mean derive it, not disable it. (default: -1 A sixth of the database connection pool size, never less than 2)

Streaming responses

Prefix: tolgee.async.streaming

Thread pool serving streaming HTTP responses: project and glossary export, import progress streaming and machine-translation suggestion streaming.

keep-alive-seconds

How long an idle streaming thread is kept alive before it is released, in seconds. (default: 60 1 minute)
max-threads

How many streaming responses this instance can produce at the same time.

Each one occupies one thread and one database connection until the response is finished, so this must stay well below your database connection pool size.

There is no way to switch streaming off: 0 and any negative value mean derive it, not disable it. (default: -1 A third of the database connection pool size, never less than 2)
queue-capacity

How many streaming requests may wait for a free thread before Tolgee replies 503 Service Unavailable.

A queued request already counts against spring.mvc.async.request-timeout, so the queue cannot make a request wait longer than that — it absorbs bursts while threads turn over, and requests that still cannot be served in time are answered rather than left hanging. (default: -1 50, or max-threads if that is larger)

Authentication

Prefix: tolgee.authentication

Configuration of Tolgee's authentication.

allowed-email-domains

Email domains that are always allowed to register, even if present in the bundled disposable-domain list or in blockedEmailDomains. Takes precedence over both. Useful for rescuing a domain that the bundled list flags by mistake. (default: [])
block-disposable-emails

When enabled, registrations from disposable / throw-away email providers (e.g. mailinator.com) are rejected. The blocklist is a bundled snapshot of the community-maintained disposable-email-domains list.

Use blockedEmailDomains to block additional domains and allowedEmailDomains to allow domains that the bundled list flags by mistake. (default: true)
block-email-aliases

When enabled, sign-ups whose email is a subaddressing alias of an existing account are rejected. For example, when foo@gmail.com already exists, foo+anything@gmail.com is treated as the same account. The comparison is also case-insensitive.

note
This only affects new registrations — existing accounts and login are unaffected. ::: (default: true)
blocked-email-domains

Additional email domains to block from registration, on top of the bundled disposable-domain list. Matched case-insensitively against the domain part of the email. (default: [])
create-demo-for-initial-user

When enabled, creates Demo project and quick start guide for inital user (default: true)
enabled

Whether authentication is enabled. When authentication is disabled, there are no login screen and no permission control. Users get automatically logged in as the administrator account of the Tolgee instance. This is very useful, when you want to use Tolgee on your local machine, or you just want to test it. (default: true when running with Java directly, false when running via Docker.)
initial-password

Password of initial user. If unspecified, a random password will be generated and stored in the initial.pwd file, located at the root of Tolgee's data path.

tip
Once set, you don't need to set this property anymore, and it is recommended you unset it so the password is not stored in plaintext in config files.
If you set this field to something else, the initial user's password will be updated unless the password was updated once via the Tolgee web UI.
initial-username

Username of initial user.

tip
Tolgee will ask for an email instead of a username - don't worry, just give it the username specified here.

(default: admin)
jwt-expiration

Expiration time of generated JWT tokens in milliseconds. (default: 604800000 = 7 days)
jwt-secret

Secret used to sign JWT authentication tokens with. It will be generated automatically, if not provided. You will be fine with 64 characters long random string.

warning
When running multiple replicas, it is required to set it, or you will be constantly logged out otherwise.
jwt-super-expiration

Expiration time of generated JWT tokens for superuser in milliseconds. (default: 3600000 = 1 hour)
native-enabled

Whether to enable Tolgee-native authentication and registration. When set to false, users will only be able to register and login via third-party SSO options (e.g. OAuth). (default: true)
needs-email-verification

Whether users need to verify their email addresses when creating their account. Requires a valid SMTP configuration. (default: false)
registrations-allowed

Whether users are allowed to register on Tolgee. When set to false, existing users must send invites to projects to new users for them to be able to register. When SSO is enabled, users can still register via SSO, even if this setting is set to false. (default: false)
secured-image-retrieval

Whether image assets should be protected by Tolgee. When enabled, all images are served with an access token valid for a set period of time to prevent unauthorized access to images. (default: false)
secured-image-timestamp-max-age

Expiration time of a generated image access token in milliseconds. (default: 7200000 = 2 hours)
user-can-create-organizations

Whether regular users are allowed to create organizations. When false, only administrators can create organizations. By default, when the user has no organization, one is created for them; this doesn't apply when this setting is set to false. In that case, the user without organization has no permissions on the server.

When SSO authentication is enabled, users created by SSO don't have their own organization automatically created no matter the value of this setting. (default: true)
~~create-initial-user~~

Removed in: 3.31.0

If true, Tolgee creates initial user on first start-up. (default: true)
~~ldap.*~~

Removed in: 3.31.0

LDAP-related settings.
~~user-can-create-projects~~

Removed in: 2.33.0

Whether regular users are allowed to create projects. When disabled, only administrators can create projects (default: true)

GitHub

Prefix: tolgee.authentication.github

info

GitHub authentication can be used in combination with native authentication.

authorization-url

URL to the OAuth authorization screen. Useful if you want to authenticate against a self-hosted GitHub Enterprise Server. (default: https://github.com/login/oauth/access_token)
client-id

OAuth Client ID, obtained in GitHub administration.
client-secret

OAuth Client secret, obtained in GitHub administration.
user-url

URL to GitHub's /user API endpoint. Useful if you want to authenticate against a self-hosted GitHub Enterprise Server. (default: https://api.github.com/user)

Google

Prefix: tolgee.authentication.google

The following instructions explain how to set up Google OAuth. Setting up OAuth 2.0.

authorization-url

URL to Google /token API endpoint. This usually does not need to be changed. (default: https://oauth2.googleapis.com/token)
client-id

OAuth Client ID, obtained in Google Cloud Console.
client-secret

OAuth Client secret, obtained in Google Cloud Console.
user-url

URL to Google /userinfo API endpoint. This usually does not need to be changed. (default: https://www.googleapis.com/oauth2/v3/userinfo)
workspace-domain

The registration can be limited to users of a Google Workspace domain. Multiple Google Workspace domains can be separated by a comma ,. If nothing is set, anyone can log in with their Google account.

OAuth2

Prefix: tolgee.authentication.oauth2

OAuth 2.0 is the industry-standard protocol for authorization. This enables the integration of a wide range of authorization providers into tolgee, such as Auth0, KeyCloak, Okta and others.

authorization-url

URL to OAuth2 authorize API endpoint. This endpoint will exposed to the frontend.
client-id

OAuth2 Client ID
client-secret

OAuth2 Client secret
scopes

Oauth2 scopes (as list) Tolgee absolutely requires rights to view the email and user information (also known as openid data). In most cases the scopes openid email profile is used for this. (But can also be different depending on the provider) (default: [])
token-url

URL to OAuth2 token API endpoint.
user-url

URL to OAuth2 userinfo API endpoint.

Server wide Single Sign-On

Prefix: tolgee.authentication.sso-global

Single sign-on (SSO) is an authentication process that allows a user to access multiple applications with one set of login credentials. To use SSO in Tolgee, can either configure global SSO settings in this section or in refer to sso-organizations section for enabling the per Organization mode.

There is a significant difference between global and per organization SSO: Global SSO can handle authentication for all server users no matter which organizations they belong to, while per organization SSO can handle authentication only for users of the organization and such users cannot be members of any other organization. SSO users associated with per organization SSO have no rights to create or manage organizations. Global SSO users should be invited to organizations they need to have access to. Per organization SSO users are automatically added to the organization they belong to.

authorization-uri

URL to redirect users for authentication
client-id

Unique identifier for an application
client-secret

Key used to authenticate the application
custom-login-text

Custom text for the SSO login page.
custom-logo-url

Custom logo URL to be displayed on the login screen. Can be set only when nativeEnabled is false.
domain

Used to identify the organization on login page
enabled

Enables SSO authentication on global level - as a login method for the whole server (default: false)
force

When true, users with an email matching the organization's domain must sign in using SSO (default: false)
session-expiration-minutes

Minutes after which the server will recheck the user's with the SSO provider to ensure the user account is still valid. This is to prevent the user from being able to access the server after the account has been disabled or deleted in the SSO provider. (default: 10)
token-uri

URL for exchanging authorization code for tokens

Per-Organization Single Sign-On

Prefix: tolgee.authentication.sso-organizations

Single sign-on (SSO) is an authentication process that allows a user to access multiple applications with one set of login credentials. To use SSO in Tolgee, can either configure global SSO settings in sso-global section or in the per Organization mode by setting the enable to true in this section and configuring it separately for each organization in the organization settings.

allow-local-addresses

When enabled, per-organization SSO provider URLs (tokenUri, authorizationUri) may target otherwise-blocked address ranges — loopback, private/site-local, link-local, IPv6 unique-local, multicast and wildcard/any-local addresses. Useful when the identity provider runs on an internal network in a self-hosted deployment.

danger
This removes SSRF protection for SSO provider URLs. Keep it disabled on production and multi-tenant servers — an organization owner able to configure SSO could otherwise make the server reach internal services.

(default: false)
enabled

Enables SSO authentication (default: false)
session-expiration-minutes

Minutes after which the server will recheck the user's with the SSO provider to ensure the user account is still valid. This is to prevent the user from being able to access the server after the account has been disabled or deleted in the SSO provider. (default: 10)

Batch operations

Prefix: tolgee.batch

Configuration of batch operations.

cancellation-timeout-ms

Timeout in milliseconds to wait for running job chunks to complete when cancelling a batch job. AI translation operations can take longer, so this should be set high enough to accommodate them. (default: 30000 30 seconds)
completed-job-retention-days

Retention period in days for completed batch jobs (SUCCESS, CANCELLED) (default: 3)
concurrency

How many parallel jobs can be run at once on single Tolgee instance (default: 1)
failed-job-retention-days

Retention period in days for failed batch jobs (default: 30)
job-cleanup-batch-size

Batch size for deleting old jobs (to avoid long-running transactions) (default: 1000)
job-cleanup-lock-lease-time-ms

Lock lease time in milliseconds for old job cleanup (to prevent lock expiration during long cleanups) (default: 86400000 1 day)
job-type-overrides

Per-job-type overrides. Keys are batch job type names (e.g. MACHINE_TRANSLATE), values are settings objects. Currently supports 'exclusive' (boolean) to override whether a job type requires project-level exclusive locking. (default: {})
max-per-mt-job-concurrency

Concurrency among all tolgee instances per one machine translation job .Higher concurrency provides faster and distributed processing, but can lead to hitting rate limit on OpenAI, as well as getting over the limit of availableCredits: at the beginning, we only check, that the organization has availableCredits > 0 and only when we have the result from OpenAI,we are able to calculate how many credits to charge the organization. In the Tolgee Cloud it is set to 1. (default: -1 Unlimited (within tolgee.batch.concurrency))
old-job-cleanup-delay-in-ms

Delay between old batch job cleanup runs in milliseconds (default: 28800000 8 hours)
old-job-cleanup-enabled

Enable scheduled cleanup of old batch jobs (default: true)

Cache

Prefix: tolgee.cache

At the expense of higher memory footprint, Tolgee can use a cache to reduce the stress on the database and fetch the data it needs faster. Cache is also used to track certain states, such as rate limits.

caffeine-max-size

Maximum size of the Caffeine cache. When exceeded, some entries will be purged from cache. Set to -1 to disable size limitation. This has no effect when Redis cache is used. See Caffeine's documentation about size-based eviction (default: -1)
default-ttl

TTL of cache data, in milliseconds. (default: 7200000 ≈ 2 hours)
enabled

Whether Tolgee should use a cache. (default: false)
use-redis

Whether Tolgee should use Redis to store cache data instead of storing it in-memory.

info
In a distributed environment, you should use a Redis server to ensure consistent enforcement of rate limits, as they heavily rely on cache. For a simple single-node deployment, in-memory cache is sufficient.

info
Tolgee uses Redisson to interface with the Redis server. You can find the properties Redisson expects here.

(default: false)

Content Delivery

Prefix: tolgee.content-delivery

These properties are used to configure default server content delivery storage.

To get content delivery working, you have to configure the Storage (e.g. S3 or Blob).

public-url-prefix

The prefix URL where the content is accessible from the public. If this property is not null, content delivery will be enabled on your server.

For example, if you set this property to https://cdn.example.com/

Cache purging

Prefix: tolgee.content-delivery.cache-purging

Several services can be used as cache. Tolgee is able to purge the cache when new files are published when this configuration is set.

aws-cloudfront

Prefix: tolgee.content-delivery.cache-purging.aws-cloudfront

access-key
content-root
distribution-id
secret-key

azure-front-door

Prefix: tolgee.content-delivery.cache-purging.azure-front-door

client-id
client-secret
content-root
endpoint-name
profile-name
resource-group-name
subscription-id
tenant-id

bunny

Prefix: tolgee.content-delivery.cache-purging.bunny

api-key
content-delivery-cache-purging-type
enabled
url-prefix

cloudflare

Prefix: tolgee.content-delivery.cache-purging.cloudflare

api-key
content-delivery-cache-purging-type
enabled
max-files-per-request

Number of paths to purge in one request. (Cloudflare limit is 30 now, but it might be subject to change) (default: 30)
origins

If cache is filled with specific Origin header, it can be purged only if the purge request specifies the same Origin header. Here you can specify comma separated list of origins. e.g. https://example.com,https://example2.com

Read more in the Cloudflare docs.
url-prefix
zone-id

storage

Prefix: tolgee.content-delivery.storage

Configuration of the storage. You have to configure exactly one storage.

azure

Prefix: tolgee.content-delivery.storage.azure

Configuration of Azure Blob storage

connection-string
container-name

s3

Prefix: tolgee.content-delivery.storage.s3

Configuration of S3 bucket

access-key
bucket-name
endpoint
path
secret-key
signing-region

File storage

Prefix: tolgee.file-storage

Configuration of Tolgee file storage.

fs-data-path

Path to directory where Tolgee will store its files. (default: ~/.tolgee/ , with docker /data/)

Azure Blob Storage

Prefix: tolgee.file-storage.azure

Tolgee supports storing its files in Azure Blob Storage. When enabled, Tolgee will store all its files in the configured container rather than in filesystem. The container has to exist already.

connection-string

Connection string of the Azure Storage account.
container-name

Name of the container where Tolgee will store its files.
enabled

Whether Azure Blob Storage is enabled. If enabled, you need to set all remaining properties below. Cannot be enabled together with S3. (default: false)

S3

Prefix: tolgee.file-storage.s3

Tolgee supports storing its files on an S3-compatible storage server. When enabled, Tolgee will store all its files on the S3 server rather than in filesystem.

access-key

Access key for the S3 server. (optional if you are authenticating with a different method, like STS Web Identity)
bucket-name

Name of the bucket where Tolgee will store its files.
enabled

Whether S3 is enabled. If enabled, you need to set all remaining properties below. (default: false)
endpoint

Has to be set to a service endpoint: https://docs.aws.amazon.com/general/latest/gr/s3.html
path

Optional subfolder structure within s3 bucket to which content will be stored
secret-key

Secret key for the access key. (optional if you are authenticating with a different method, like STS Web Identity)
signing-region

Has to be set to a signing region: https://docs.aws.amazon.com/general/latest/gr/s3.html

Import

Prefix: tolgee.import

Properties for importing data to Tolgee and bulk-imports exported json files in the database during startup. Useful to quickly provision a development server, and used for testing.

base-language-tag

The language tag of the base language of the imported project (for importing data on startup). (default: en)
create-implicit-api-key

Whether an implicit API key should be created when importing data on startup.

The key is built with a predictable format: ${lowercase filename (without extension)}-${initial username}-imported-project-implicit

danger
While this is useful for tests, make sure to keep this disabled if you're importing projects on a production server as trying this predictable key may be the first thing an attacker will attempt to gain unauthorized access!

(default: false)

`dir`

File path of the directory where the files to import on startup are located.

info

Your folder structure should look like:

importDir
└─Project # the foler name is the project name
  └─validation # the foler name is namespace
    ├─ en.json # the file name is the target language
    └─ de.json # second project language

flush-batch-size

Number of keys/translations persisted per flushAndClear batch by the data importer. Smaller values reduce peak memory at the cost of more flushes; larger values do the opposite. Lower this in environments where the import OOMs at scale. (default: 10000)
store-files-for-debugging

If true, uploaded files will be stored in configured file storage for future debugging. Such data is not automatically removed after successful import. You have to clean-up manually! (default: false)

LanguageTool

Prefix: tolgee.language-tool

Configuration for an external LanguageTool server used for spelling and grammar checks. LanguageTool container (erikvl87/languagetool:6.7) must be deployed as a separate container.

connect-timeout-seconds

TCP connect timeout for LanguageTool HTTP calls, in seconds. (default: 5)
max-concurrent-requests

Maximum number of concurrent /v2/check requests a single Tolgee instance is allowed to send to the LanguageTool server. (default: 2)
read-timeout-seconds

Read (socket) timeout for LanguageTool HTTP calls, in seconds. (default: 60)
url

URL of the LanguageTool server (e.g. http://languagetool:8010). When empty, spelling and grammar checks are disabled.

LLM Providers

Prefix: tolgee.llm

LLM Providers configuration

default-enabled

Whether llm-powered machine translation is enabled. (default: true)
default-primary

Whether to use llm machine translation as a primary translation engine. (default: true)
default-provider

Name of the provider used when a prompt selects the default provider. The name must match one of the configured providers (the fallbacks mapping is applied if the provider was renamed). When unset, the first enabled provider is used.
enabled

Enable/disable AI translator (default: enabled if there is at least one provider)
fallbacks

Named fallback mapping. When a provider is not found, Tolgee will try the fallback provider.
```
fallbacks:
  openai: anthropic
  anthropic: google-ai
```
or using environment variables:
```
TOLGEE_LLM_FALLBACKS_OPENAI=anthropic
TOLGEE_LLM_FALLBACKS_ANTHROPIC=google-ai
```
(default: {})

`provider-defaults`

Map of provider defaults keyed by provider name. Use this to separate non-secret configuration (model, prices, type) from secrets (API keys) in Kubernetes deployments.

provider-defaults:
  gpt-5-mini:
    type: OPENAI
    model: gpt-5-mini
    token-price-in-credits-input: 2.0
    token-price-in-credits-output: 1.5

or using environment variables (in a ConfigMap):

TOLGEE_LLM_PROVIDER_DEFAULTS_GPT_5_MINI_TYPE=OPENAI
TOLGEE_LLM_PROVIDER_DEFAULTS_GPT_5_MINI_MODEL=gpt-5-mini
TOLGEE_LLM_PROVIDER_DEFAULTS_GPT_5_MINI_TOKEN_PRICE_IN_CREDITS_INPUT=2.0
TOLGEE_LLM_PROVIDER_DEFAULTS_GPT_5_MINI_TOKEN_PRICE_IN_CREDITS_OUTPUT=1.5

Then supply only the API key via the providers list (in a Secret):

TOLGEE_LLM_PROVIDERS_0_NAME=gpt-5-mini
TOLGEE_LLM_PROVIDERS_0_API_KEY=sk-proj-...

(default: {})

providers

List of LLM providers. When provider-defaults is also set, list entries are merged with the matching map entry (by name). List values override map defaults only when explicitly set (non-null for nullable fields, non-default for type / maxTokens). enabled is always taken from the list entry.

providers:
  - name: openai-gpt-4o-mini
    type: OPENAI
    api-key: "myApiKey"
    api-url: "https://api.openai.com"
    model: gpt-4o-mini
    format: "json_schema"

or using environment variables:

TOLGEE_LLM_PROVIDERS_0_NAME=MySuperDuperAI
TOLGEE_LLM_PROVIDERS_0_TYPE=OPENAI
TOLGEE_LLM_PROVIDERS_0_API_KEY=myApiKey
TOLGEE_LLM_PROVIDERS_0_API_URL=https://api.openai.com
TOLGEE_LLM_PROVIDERS_0_MODEL=gpt-4o-mini
TOLGEE_LLM_PROVIDERS_0_FORMAT=json_schema

Check llm providers documentation for more information.

api-key

Provider API Key (optional for some providers)
api-url

Provider API Url
attempts

Specify attempts timeout(s) (Example: [30, 30] - Tolgee will make two attempts, each with timeout of 30s)
deployment

Provider deployment (optional for some providers)
enabled

Enable/disable provider (default: true)
format

Set to json_schema if the API supports JSON Schema
max-tokens

Maximum number of tokens to generate. max_completion_tokens option for OpenAI API. max_tokens for Anthropic API.(default:8192`)
model

Provider model (optional for some providers)
name

User visible provider name (default: default)
priority

Load-balancing instruction HIGH = used for suggestions, LOW = used for batch operations
reasoning-effort

ChatGPT reasoning effort
type

Provider type, an API type (default: OPENAI)

Machine Translation

Prefix: tolgee.machine-translation

Configuration of Machine Translation services.

free-credits-amount

Amount of machine translations users of the Free tier can request per month. Used by Tolgee Cloud, see pricing. Set to -1 to disable credit-based limitation. (default: -1)

AWS Amazon Translate

Prefix: tolgee.machine-translation.aws

See AWS's Amazon Translate page for more information and applicable pricing.

access-key

AWS access key. (optional if you are authenticating with a different method, like STS Web Identity)
default-enabled

Whether AWS-powered machine translation is enabled. (default: true)
default-primary

Whether to use AWS Amazon Translate as a primary translation engine. (default: false)
enabled

If you are authenticating using a different method than explicit access key and secret key, which implicitly enable AWS Translate, you should enable AWS Translate using this option.
region

AWS region. (default: eu-central-1)
secret-key

AWS secret key. (optional if you are authenticating with a different method, like STS Web Identity)

Azure Cognitive Translation

Prefix: tolgee.machine-translation.azurecognitive

See Azure Cognitive Translation page for more information and applicable pricing.

auth-key

Azure Cognitive Translation auth key.
default-enabled

Whether Azure Cognitive Translation is enabled. (default: true)
default-primary

Whether to use Azure Cognitive Translation as a primary translation engine. (default: false)
region

Azure Cognitive Translation region.

Baidu Translate

Prefix: tolgee.machine-translation.baidu

See Baidu's page (in Chinese) for more information and applicable pricing.

action

Whether the resulting translation should be changed according to the user-defined dictionary. The dictionary used can be modified at Manage Terms (login required). (default: false)
app-id

Baidu Translate App ID.
app-secret

Baidu Translate Secret key.
default-enabled

Whether Baidu-powered machine translation is enabled. (default: true)
default-primary

Whether to use Baidu Translate as a primary translation engine. (default: false)

DeepL

Prefix: tolgee.machine-translation.deepl

See DeepL's page for more information and applicable pricing.

auth-key

DeepL auth key. Both key types (commercial and free) are supported.
default-enabled

Whether DeepL-powered machine translation is enabled. (default: true)
default-primary

Whether to use DeepL as a primary translation engine. (default: false)
optional-parameters

DeepL parameters which should be set for deepl api usage (Optional)

Google Cloud Translation

Prefix: tolgee.machine-translation.google

See Google Cloud Translation page for more information and applicable pricing.

api-key

Google Cloud Translation API key.
default-enabled

Whether Google-powered machine translation is enabled. (default: true)
default-primary

Whether to use Google Cloud Translation as a primary translation engine. (default: true)

OAuth2 authorization server

Prefix: tolgee.oauth2

Settings for Tolgee acting as an OAuth 2.1 authorization server (browser-extension login, MCP).

access-token-validity-minutes

How long an issued OAuth access token stays valid, in minutes. (default: 30)
authorization-code-validity-seconds

How long an authorization code can be exchanged for tokens after it was issued, in seconds. (default: 300)
browser-extension-redirect-uris

Exact redirect URIs of the Tolgee browser extension, e.g. https://<extension-id>.chromiumapp.org/. The extension OAuth client is only registered when this is set. (default: [])
cli-redirect-uris

Loopback redirect URIs of the Tolgee CLI (RFC 8252), e.g. http://127.0.0.1:9876/callback. Prefer the loopback IP literal over localhost, which RFC 8252 section 7.3 marks NOT RECOMMENDED: a client resolving localhost may end up listening on interfaces other than the loopback one. The CLI OAuth client is only registered when this is set.

info
A loopback redirect cannot be tied to one local application, so any process on the machine that knows the client id can start an authorization for it. The user still has to approve the consent screen, but leave this unset unless the CLI is actually in use.

(default: [])
consent-validity-seconds

How long the user has to complete the consent screen before the pending authorization goes stale, in seconds. (default: 900)
grant-cleanup-cron

Cron expression for the job that removes spent grants past their retention window and consents the user never completed. Spring's six-field format (second, minute, hour, day, month, weekday). (default: 0 0 3 * * *)
grant-retention-days

How long a spent OAuth grant is kept after its last credential expired, in days. It holds a used code's row so a replayed code is still recognised. A consent the user never completed is not kept for this window — it is deleted once its own short deadline passes. (default: 7)
refresh-token-validity-days

How long an issued OAuth refresh token stays valid, in days. Each refresh issues a new one and restarts this window, so it bounds how long a grant may sit unused — not how long it may live. (default: 30)

Postgres autostart

Prefix: tolgee.postgres-autostart

Defines whether and how is PostgreSQL started on Tolgee startup.

container-name

The container name of the Postgres container. This setting is applicable only for DOCKER mode. (default: tolgee_postgres)
database-name

The name of the database created to store Tolgee data. (default: postgres)
enabled

Whether to start PostgreSQL on Tolgee startup. (default: true)
max-wait-time

The max time to wait for running postgres in seconds. (default: 300)
mode

How is Tolgee running PostgreSQL.

Options:
- DOCKER - Tolgee tries to run Postgres Docker container in your machine. This is default option when running Tolgee using Java. See Running with Java.
- EMBEDDED - Tolgee tries to run it's embedded PostgreSQL which is bundled in the tolgee/tolgee Docker image.
EMBEDDED is deprecated. Tolgee v4 removes the bundled PostgreSQL from the tolgee/tolgee image, so setups using it have to move to an external database before upgrading. See Migrate from the bundled database. (default: DOCKER)
password

Database password to bootstrap Postgres with. (default: postgres)
port

The port of Postgres to listen on host machine. This setting is applicable only for DOCKER mode. (default: 25432)
stop

When true, Tolgee will stop the Postgres container on Tolgee shutdown. This setting is applicable only for DOCKER mode. (default: true)
user

Database user to bootstrap Postgres with. (default: postgres)

Rate limits

Prefix: tolgee.rate-limits

Configuration of the rate limit behavior of the server. Rate limits are used to protect against server overload and/or abuse, and are enabled by default.

You can disable global, per-endpoint and auth-related rate limits, or configure global rate limits. Per-endpoint and auth-related rate limits are fixed and cannot be configured.

activity-request-limit

Amount of activity requests a user can do in a single time window. (default: 100)
activity-request-window

Size, in milliseconds, of the time window for activity-based limiting. (default: 300000 = 5 minutes)
authentication-limits

Control whether per-endpoint limits on authentication-related endpoints are enabled or not.

warning
It is strongly recommended to keep these limits enabled. They act as a protection layer against brute-force attacks on the login (and register) prompt.

(default: true)
email-verification-request-limit
email-verification-request-limit-enabled
email-verification-request-window
enabled

To turn all rate limits off, set this value to false.

danger
This field is deprecated and will be removed with Tolgee 4. If set to false, it will take priority over the more granular global-limits, endpoint-limits and authentication-limits and all limits will be disabled.

(default: true)
endpoint-limits

Control whether per-endpoint limits on the API are enabled or not. Does not affect authentication-related endpoints, these are controlled by authentication-limits. (default: true)
export-request-limit

Amount of export requests a user can do in a single time window. (default: 100)
export-request-window

Size, in milliseconds, of the time window for export-based limiting. (default: 300000)
global-limits

Control whether global limits on the API are enabled or not. (default: true)
ip-request-limit

Amount of requests an IP address can do in a single time window. (default: 20000)
ip-request-window

Size, in milliseconds, of the time window for IP-based limiting. (default: 300000 = 5 minutes)
max-strikes-before-block

Number of rate limit violations before the server stops responding to the client. After this threshold, the connection is dropped without sending a response body, saving bandwidth. Set to 0 to disable connection dropping (always send 429 responses). (default: 3)
strike-reset-window-ms

Time window, in milliseconds, after which strikes are reset if the client behaves well. If a client doesn't hit rate limits for this duration, their strike count is reset to zero. (default: 60000 = 1 minute)
translation-request-limit

Amount of translation requests a user can do in a single time window. (default: 100)
translation-request-window

Size, in milliseconds, of the time window for translation-based limiting. (default: 300000 = 5 minutes)
user-request-limit

Amount of requests a user can do in a single time window. (default: 400)
user-request-window

Size, in milliseconds, of the time window for user-based limiting. (default: 60000 = 1 minute)

reCAPTCHA

Prefix: tolgee.recaptcha

When configured, reCAPTCHA v3 is used to protect the sign up page against bots. By default, reCAPTCHA is disabled.

To enable it, you first need to register a new site on reCAPTCHA. Make sure to select reCAPTCHA v3 when registering your site.

secret-key

Secret key for communication between your site and reCAPTCHA.
site-key

Site key for use the HTML code your site serves to users.

Sentry

Prefix: tolgee.sentry

Tolgee uses Sentry for error reporting.

client-dsn

Client DSN. If unset, error reporting is disabled on the server.
server-dsn

Server DSN. If unset, error reporting is disabled on the server.
traces-sample-rate

Sample rate for Sentry traces. If unset, traces are disabled on the server.

slack

Prefix: tolgee.slack

client-id
client-secret
signing-secret
token

SMTP

Prefix: tolgee.smtp

Configuration of SMTP server used to send emails to your users like password reset links or notifications.

For AWS SES it would look like this:

tolgee.smtp.host=email-smtp.eu-central-1.amazonaws.com
tolgee.smtp.username=*****************
tolgee.smtp.password=*****************
tolgee.smtp.port=465
tolgee.smtp.auth=true
tolgee.smtp.ssl-enabled=true
tolgee.smtp.from=Tolgee <no-reply@tolgee.yourserver.something>

auth

Whether authentication is enabled. (default: false)
from

The sender name and address in standard SMTP format.
host

SMTP server host
password

Password for SMTP authentication
port

SMTP server port (default: 25)
ssl-enabled

Whether SSL is enabled. (default: false)
tls-enabled

Whether TLS is enabled. (default: false)
tls-required

Whether TLS is required. (default: false)
username

The username for SMTP authentication

Telemetry

Prefix: tolgee.telemetry

By default, self-hosted instances send anonymous data about usage to help us improve Tolgee.

info

This was added in Tolgee Platform v3.23.0

Once a day we collect following data

number of projects
number of languages
number of translations
number of users

We don't collect any other data. Please leave telemetry enabled to help us improve Tolgee.

enabled

Whether telemetry is enabled (default: true)

Webhooks

Prefix: tolgee.webhook

Configuration for webhook behavior.

allow-local-addresses

When enabled, webhook URLs may target otherwise-blocked address ranges — loopback, private/site-local, link-local, IPv6 unique-local, multicast and wildcard/any-local addresses. Useful for local development and integration testing.

danger
This removes SSRF protection for webhook targets. Keep it disabled on production and multi-tenant servers — anyone able to configure a webhook could otherwise reach internal services.

(default: false)
auto-disable-after-days

Number of days of continuous failure before a webhook is automatically disabled. (default: 3)
auto-disable-enabled

Whether the automatic disabling of failing webhooks is enabled. (default: true)
auto-disable-warning-after-hours

Number of hours of continuous failure before a warning email is sent. (default: 6)

Websocket

Prefix: tolgee.websocket

Configuration specific to the use of Websocket.

use-redis

Whether to use Redis for Websocket events (default: false)

Full configuration example

YAML
.env
application.properties

Details

config.yaml
server:
  port: 8080
spring:
  datasource:
    url:
    username:
    password:
tolgee:
  back-end-url:
  file-storage-url:
  front-end-url:
  max-screenshots-per-key: 20
  max-translation-text-length: 10000
  max-upload-file-size: 51200
  translations-view-languages-limit: -1
  async:
    background:
      keep-alive-seconds: 60
      max-threads: -1
    streaming:
      keep-alive-seconds: 60
      max-threads: -1
      queue-capacity: -1
  authentication:
    allowed-email-domains: []
    block-disposable-emails: true
    block-email-aliases: true
    blocked-email-domains: []
    create-demo-for-initial-user: true
    enabled: true
    initial-password:
    initial-username: admin
    jwt-expiration: 604800000
    jwt-secret:
    jwt-super-expiration: 3600000
    native-enabled: true
    needs-email-verification: false
    registrations-allowed: false
    secured-image-retrieval: false
    secured-image-timestamp-max-age: 7200000
    user-can-create-organizations: true
    github:
      authorization-url: https://github.com/login/oauth/access_token
      client-id:
      client-secret:
      user-url: https://api.github.com/user
    google:
      authorization-url: https://oauth2.googleapis.com/token
      client-id:
      client-secret:
      user-url: https://www.googleapis.com/oauth2/v3/userinfo
      workspace-domain:
    oauth2:
      authorization-url:
      client-id:
      client-secret:
      scopes: []
      token-url:
      user-url:
    sso-global:
      authorization-uri:
      client-id:
      client-secret:
      custom-login-text:
      custom-logo-url:
      domain:
      enabled: false
      force: false
      session-expiration-minutes: 10
      token-uri:
    sso-organizations:
      allow-local-addresses: false
      enabled: false
      session-expiration-minutes: 10
  batch:
    cancellation-timeout-ms: 30000
    completed-job-retention-days: 3
    concurrency: 1
    failed-job-retention-days: 30
    job-cleanup-batch-size: 1000
    job-cleanup-lock-lease-time-ms: 86400000
    job-type-overrides: {}
    max-per-mt-job-concurrency: -1
    old-job-cleanup-delay-in-ms: 28800000
    old-job-cleanup-enabled: true
  cache:
    caffeine-max-size: -1
    default-ttl: 7200000
    enabled: false
    use-redis: false
  content-delivery:
    public-url-prefix:
    cache-purging:
      aws-cloudfront:
        access-key:
        content-root:
        distribution-id:
        secret-key:
      azure-front-door:
        client-id:
        client-secret:
        content-root:
        endpoint-name:
        profile-name:
        resource-group-name:
        subscription-id:
        tenant-id:
      bunny:
        api-key:
        content-delivery-cache-purging-type: BUNNY
        enabled: false
        url-prefix:
      cloudflare:
        api-key:
        content-delivery-cache-purging-type: CLOUDFLARE
        enabled: false
        max-files-per-request: 30
        origins:
        url-prefix:
        zone-id:
    storage:
      azure:
        connection-string:
        container-name:
      s3:
        access-key:
        bucket-name:
        endpoint:
        path:
        secret-key:
        signing-region:
  file-storage:
    fs-data-path: ~/.tolgee/
    azure:
      connection-string:
      container-name:
      enabled: false
    s3:
      access-key:
      bucket-name:
      enabled: false
      endpoint:
      path:
      secret-key:
      signing-region:
  import:
    base-language-tag: en
    create-implicit-api-key: false
    dir:
    flush-batch-size: 10000
    store-files-for-debugging: false
  language-tool:
    connect-timeout-seconds: 5
    max-concurrent-requests: 2
    read-timeout-seconds: 60
    url:
  llm:
    default-enabled: true
    default-primary: true
    default-provider:
    enabled:
    fallbacks: {}
    provider-defaults: {}
    providers:
    -
      api-key:
      api-url:
      attempts:
      deployment:
      enabled: true
      format:
      max-tokens: 8192
      model:
      name: default
      priority:
      reasoning-effort:
      type: OPENAI
  machine-translation:
    free-credits-amount: -1
    aws:
      access-key:
      default-enabled: true
      default-primary: false
      enabled:
      region: eu-central-1
      secret-key:
    azure:
      auth-key:
      default-enabled: true
      default-primary: false
      region:
    baidu:
      action: false
      app-id:
      app-secret:
      default-enabled: true
      default-primary: false
    deepl:
      auth-key:
      default-enabled: true
      default-primary: false
      optional-parameters:
    google:
      api-key:
      default-enabled: true
      default-primary: true
  oauth2:
    access-token-validity-minutes: 30
    authorization-code-validity-seconds: 300
    browser-extension-redirect-uris: []
    cli-redirect-uris: []
    consent-validity-seconds: 900
    grant-cleanup-cron: 0 0 3 * * *
    grant-retention-days: 7
    refresh-token-validity-days: 30
  postgres-autostart:
    container-name: tolgee_postgres
    database-name: postgres
    enabled: true
    max-wait-time: 300
    mode: DOCKER
    password: postgres
    port: 25432
    stop: true
    user: postgres
  rate-limits:
    activity-request-limit: 100
    activity-request-window: 300000
    authentication-limits: true
    email-verification-request-limit: 2
    email-verification-request-limit-enabled: true
    email-verification-request-window: 60000
    enabled: true
    endpoint-limits: true
    export-request-limit: 100
    export-request-window: 300000
    global-limits: true
    ip-request-limit: 20000
    ip-request-window: 300000
    max-strikes-before-block: 3
    strike-reset-window-ms: 60000
    translation-request-limit: 100
    translation-request-window: 300000
    user-request-limit: 400
    user-request-window: 60000
  recaptcha:
    secret-key:
    site-key:
  sentry:
    client-dsn:
    server-dsn:
    traces-sample-rate:
  slack:
    client-id:
    client-secret:
    signing-secret:
    token:
  smtp:
    auth: false
    from:
    host:
    password:
    port: 25
    ssl-enabled: false
    tls-enabled: false
    tls-required: false
    username:
  telemetry:
    enabled: true
  webhook:
    allow-local-addresses: false
    auto-disable-after-days: 3
    auto-disable-enabled: true
    auto-disable-warning-after-hours: 6
  websocket:
    use-redis: false

Server settings​

port​

Spring settings​

Data source settings​

url​

username​

password​

Tolgee​

back-end-url​

file-storage-url​

front-end-url​

max-screenshots-per-key​

max-translation-text-length​

max-upload-file-size​

translations-view-languages-limit​

Asynchronous execution​

Background tasks​

keep-alive-seconds​

max-threads​

Streaming responses​

keep-alive-seconds​

max-threads​

queue-capacity​

Authentication​

allowed-email-domains​

block-disposable-emails​

block-email-aliases​

blocked-email-domains​

create-demo-for-initial-user​

enabled​

initial-password​

initial-username​

jwt-expiration​

jwt-secret​

jwt-super-expiration​

native-enabled​

needs-email-verification​

registrations-allowed​

secured-image-retrieval​

secured-image-timestamp-max-age​

user-can-create-organizations​

create-initial-user​

ldap.*​

user-can-create-projects​

GitHub​

authorization-url​

client-id​

client-secret​

user-url​

Google​

authorization-url​

client-id​

client-secret​

user-url​

workspace-domain​

OAuth2​

authorization-url​

client-id​

client-secret​

scopes​

token-url​

user-url​

Server wide Single Sign-On​

authorization-uri​

client-id​

client-secret​

custom-login-text​

custom-logo-url​

domain​

enabled​

force​

session-expiration-minutes​

token-uri​

Per-Organization Single Sign-On​

allow-local-addresses​

enabled​

session-expiration-minutes​

Batch operations​

cancellation-timeout-ms​

completed-job-retention-days​

Server settings

`port`

Spring settings

Data source settings

`url`

`username`

`password`

Tolgee

`back-end-url`

`file-storage-url`

`front-end-url`

`max-screenshots-per-key`

`max-translation-text-length`

`max-upload-file-size`

`translations-view-languages-limit`

Asynchronous execution

Background tasks

`keep-alive-seconds`

`max-threads`

Streaming responses

`keep-alive-seconds`

`max-threads`

`queue-capacity`

Authentication

`allowed-email-domains`

`block-disposable-emails`

`block-email-aliases`

`blocked-email-domains`

`create-demo-for-initial-user`

`enabled`

`initial-password`

`initial-username`

`jwt-expiration`

`jwt-secret`

`jwt-super-expiration`

`native-enabled`

`needs-email-verification`

`registrations-allowed`

`secured-image-retrieval`

`secured-image-timestamp-max-age`

`user-can-create-organizations`

`create-initial-user`

`ldap.*`

`user-can-create-projects`

GitHub

`authorization-url`

`client-id`

`client-secret`

`user-url`

Google

`authorization-url`

`client-id`

`client-secret`

`user-url`

`workspace-domain`

OAuth2

`authorization-url`

`client-id`

`client-secret`

`scopes`

`token-url`

`user-url`

Server wide Single Sign-On

`authorization-uri`

`client-id`

`client-secret`

`custom-login-text`

`custom-logo-url`

`domain`

`enabled`

`force`

`session-expiration-minutes`

`token-uri`

Per-Organization Single Sign-On

`allow-local-addresses`

`enabled`

`session-expiration-minutes`

Batch operations

`cancellation-timeout-ms`

`completed-job-retention-days`