docs/main/administration-guide/manage/admin/autotranslation.mdx
From Mattermost v11.5, auto-translation automatically translates channel messages into each user's preferred display language. This enables multilingual teams to collaborate without language barriers.
Auto-translation uses an asynchronous queue-based architecture. When a message is posted in a channel with auto-translation enabled, the message is queued for translation into every configured target language. Translated messages replace the original display for users whose display language matches a target language, and they can view the original text at any time by selecting the translation icon on the message. A user's translation target language is determined by their Mattermost display language (set via Settings > Display > Language); decoupling the translation target from the display language is not currently supported.
Two translation provider options are available:
Choose one of the following translation providers and follow the setup instructions for your choice.
LibreTranslate is a self-hosted, open-source machine translation engine. See the LibreTranslate installation guide for deployment instructions.
Once your LibreTranslate server is running:
libretranslate.http://libretranslate.internal:5000).The Mattermost server must be able to reach the LibreTranslate URL over the network. Ensure firewall rules and DNS resolution allow connectivity between the Mattermost server and the LibreTranslate instance.
The Agents provider uses the Mattermost Agents plugin to translate messages via a configured LLM service.
Prerequisites:
To configure:
agents.Choosing between LibreTranslate and Agents: LibreTranslate is a lightweight, self-hosted translation engine. The Agents provider uses an LLM backend and generally produces more accurate translations, especially for languages such as Japanese, Korean, and Chinese where contextual understanding improves quality. Consider your translation quality needs and existing infrastructure when choosing. LibreTranslate does not support direct translation between all language pairs; for unsupported combinations it performs a pivot translation through an intermediate language (typically English), which can reduce accuracy for those pairs.
Choosing an LLM for the Agents provider: Smaller, faster models are recommended for auto-translation. Translation is a well-defined task that doesn't benefit from the extended reasoning capabilities of larger models — larger models may actually overthink the task, adding unnecessary latency without improving quality. Choose a small, low-latency model that is currently supported by your configured LLM provider and validated in your environment.
</Tip>libretranslate or agents).The languages available in the Languages allowed list are controlled by the Available languages setting (AvailableLocales) under Site Configuration > Localization. If that field is blank, all supported languages are available; otherwise only listed languages appear as selectable auto-translation targets. The EnableExperimentalLocales setting can make additional locale codes available. Note that some locales (such as zh-Hans) are in beta — portions of the Mattermost UI may still display in English, which is a UI localization limitation and does not affect message translation.
Use the Restrict autotranslation in direct and group messages setting to control whether auto-translation can be enabled in direct and group messages.
See the auto-translation configuration reference for all available settings.
Auto-translation is managed on a per-channel basis and is disabled by default for all channels. System admins and channel admins can enable or disable auto-translation for individual channels.
Enabling auto-translation in a channel only translates new messages going forward. Existing message history is not retroactively translated.
</Note>For most deployments the default worker settings are sufficient. If your deployment has a high message volume, many configured target languages, or you observe growing translation queue depth, you may need to increase the worker count. This section explains how to calculate and monitor the right values.
When a message is posted in a channel with auto-translation enabled, it's added to a per-node translation queue. A worker picks up the post and translates it sequentially into each configured target language. Each completed language translation triggers a websocket broadcast to the channel so users see translations arrive in real time.
In a high availability deployment, each node runs its own pool of workers and processes its own queue independently.
Use the following formula to estimate how many workers each node needs:
required_workers = ceil(
(posts_per_sec × pct_autotranslated × num_languages × avg_provider_latency_ms / 1000)
/ num_app_nodes
× 1.2
)
Where:
The following table shows results from load tests with 6,500 concurrent users, 2 app nodes, ~5 posts/sec, and ~2 s mean provider latency. The provider latency distribution used in testing was realistic, with buckets ranging from 500 ms to 10 s weighted toward the 500 ms–1.5 s range, producing a ~2 s mean.
<table> <colgroup> <col style={{width: '30%'}} /> <col style={{width: '30%'}} /> <col style={{width: '40%'}} /> </colgroup> <thead> <tr> <th>Target languages</th> <th>% autotranslated</th> <th>Workers per node</th> </tr> </thead> <tbody> <tr> <td>7</td> <td>100%</td> <td>38</td> </tr> <tr> <td>6</td> <td>100%</td> <td>32</td> </tr> <tr> <td>3</td> <td>75%</td> <td>8</td> </tr> </tbody> </table> <Note>In the 6-language test the formula yields 33, but workers were capped at 32 due to the configured maximum. Adjust the Translation workers setting to match your calculated value.
</Note>Mattermost exposes the following Prometheus metrics for auto-translation:
mattermost_autotranslation_queue_depth_total (Gauge) — current tasks waiting in the queue. A steadily rising value means workers can't keep up with incoming posts.
mattermost_autotranslation_provider_call_duration_seconds (Histogram; labels: provider, result) — translation provider latency. This is the avg_provider_latency_ms value used in the formula above. Calculate the average with the following PromQL query:
rate(mattermost_autotranslation_provider_call_duration_seconds_sum{result="success"}[10m])
/
rate(mattermost_autotranslation_provider_call_duration_seconds_count{result="success"}[10m])
mattermost_autotranslation_worker_task_duration_seconds (Histogram) — total time for a worker to process one post across all target languages.
You can also update the worker count from the command line using mmctl:
mmctl config set AutoTranslationSettings.Workers <number>
Messages are still posted normally. Translations that fail due to provider downtime are skipped, and users see the original untranslated message. When the provider recovers, new messages are translated as expected.
Supported languages depend on the translation provider:
Configure the Languages allowed setting to specify which languages all messages are translated into.