Add docs for autotranslations by BenCookie95 · Pull Request #8765 · mattermost/docs

BenCookie95 · 2026-03-04T21:10:15Z

Summary

End user docs
Admin docs
Configuration docs

Ticket Link

https://mattermost.atlassian.net/browse/MM-67781

github-actions · 2026-03-04T21:13:53Z

Newest code from mattermost has been published to preview environment for Git SHA c92dcf4

esethna · 2026-03-05T00:05:51Z

Thanks @BenCookie95! Can you please help remove the "docs/needed" label and replace with "docs/done" label on any code PRs that are covered by this docs PR?

@Combs7th can you help do a first pass review on this?

esethna · 2026-03-05T00:10:32Z

source/administration-guide/manage/admin/autotranslation.rst

+  - **LibreTranslate**: A running LibreTranslate server reachable from the Mattermost server.
+  - **Agents**: The :doc:`Mattermost Agents plugin </administration-guide/configure/agents-admin-guide>` installed and configured with at least one LLM service.
+
+Enable autotranslation


This should probably be after the step of selecting and configuring your translation provider.

esethna · 2026-03-05T00:11:05Z

source/administration-guide/manage/admin/autotranslation.rst

+- **LibreTranslate**: A self-hosted, open-source machine translation engine.
+- **Agents**: Uses the Mattermost Agents plugin with a configured LLM backend.
+
+Before you begin


We can probably create a heading to house everything related to setting up and selecting your translation provider

esethna · 2026-03-05T00:13:40Z

source/administration-guide/manage/admin/autotranslation.rst

+
+   **Choosing an LLM for the Agents provider**: Smaller, faster models are recommended for autotranslation. 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. A model like ``gpt-3.5-turbo`` provides accurate translations with lower latency.
+
+Manage autotranslation per channel


We should be more explicit in this doc about how to actually enable autotranslate in the channel. Maybe title this "Enable Auto-Translation in a Channel"

esethna · 2026-03-05T00:14:59Z

source/administration-guide/manage/admin/autotranslation.rst

+Autotranslation is managed on a per-channel basis and is disabled by default for all channels. System admins and channel admins can enable or disable autotranslation for individual channels.
+
+- When autotranslation is enabled or disabled in a channel, a system post notifies channel members of the change.
+- Use the :ref:`Restrict autotranslation in direct and group messages <administration-guide/configure/site-configuration-settings:restrict autotranslation in direct and group messages>` setting to control whether autotranslation can be enabled in direct and group messages.


This can probably move to the "enable autotranslate" section since it's a system wide configuration

esethna · 2026-03-05T00:15:32Z

source/administration-guide/manage/admin/autotranslation.rst

+- When autotranslation is enabled or disabled in a channel, a system post notifies channel members of the change.
+- Use the :ref:`Restrict autotranslation in direct and group messages <administration-guide/configure/site-configuration-settings:restrict autotranslation in direct and group messages>` setting to control whether autotranslation can be enabled in direct and group messages.
+
+Tune worker performance


This may need an intro so we are more opinionated on when and why an admin might need to do this

esethna · 2026-03-05T00:16:30Z

source/administration-guide/configure/site-configuration-settings.rst

+  :environment: MM_AUTOTRANSLATIONSETTINGS_WORKERS
+  :description: The number of concurrent translation workers per node. Default is **6**.
+
+Translation workers


I don't see this in the system console in my test server

esethna · 2026-03-05T00:17:23Z

source/administration-guide/configure/site-configuration-settings.rst


+.. _autotranslation:
+
+Autotranslation


Can we order this based on how it appears in the system console?

esethna · 2026-03-05T00:18:06Z

source/administration-guide/configure/site-configuration-settings.rst

+  :environment: MM_AUTOTRANSLATIONSETTINGS_TARGETLANGUAGES
+  :description: The languages that all messages in autotranslation-enabled channels are translated into. Every message is translated into each language in this list. Default is **["en"]**.
+
+Target languages


This is called "Languages allowed" in the sys console UI

esethna · 2026-03-05T00:18:38Z

source/administration-guide/manage/admin/autotranslation.rst

@@ -0,0 +1,199 @@
+Set up autotranslation (Beta)


Applicable throughout, in the UI we are using "Auto-translation"

esethna · 2026-03-05T00:22:49Z

source/administration-guide/manage/admin/autotranslation.rst

+Set up LibreTranslate
+---------------------
+
+`LibreTranslate <https://libretranslate.com/>`__ is a self-hosted, open-source machine translation engine. See the `LibreTranslate documentation <https://github.com/LibreTranslate/LibreTranslate>`__ for deployment instructions.


Do we have opinionated recommendations for optimal performance, in terms of hardware, install guidance (ie using it's own machine or can it be installed on the same machine as the server, etc)

Software requirements (ie version compatibility etc)

Also the link should be directly to the install docs

Combs7th · 2026-03-05T02:03:41Z

Pending the updates Eric shared above, this LGTM. Added labels and release milestone to the PR.

marianunez

Thanks Ben! Great section on the scaling 👍

Left some minor comments

marianunez · 2026-03-05T20:42:59Z

source/end-user-guide/collaborate/autotranslate-messages.rst

+
+- **Direct and group messages**: Your system admin may have restricted autotranslation in direct and group messages. If autotranslation isn't available in a direct or group message, contact your system admin.
+- **Short or mixed-language messages**: Very short messages or messages that mix multiple languages may not be reliably detected and translated.
+- **Code-only messages**: Messages that contain only code blocks are skipped and not translated.


Would we consider this a limitation or a as expected? Above we mention that code blocks are preserved

marianunez · 2026-03-05T20:45:48Z

source/administration-guide/manage/admin/autotranslation.rst

+
+From Mattermost v11.5, autotranslation automatically translates channel messages into each user's preferred display language. This enables multilingual teams to collaborate without language barriers.
+
+Autotranslation uses an asynchronous queue-based architecture. When a message is posted in a channel with autotranslation 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 toggle to view the original text at any time.


and they can toggle to view the original text at any time.

Toggle makes it sound like it can switch the view back and forth to the original to translated text but it's really just that you can view the original message at any time. However, not sure what the correct wording would be

marianunez · 2026-03-05T20:46:26Z

source/administration-guide/manage/admin/autotranslation.rst

+
+Two translation provider options are available:
+
+- **LibreTranslate**: A self-hosted, open-source machine translation engine.


We should include the link here too to their documentation, especially because it's the first time introduced in this page.

marianunez · 2026-03-05T20:49:27Z

source/administration-guide/manage/admin/autotranslation.rst

+
+.. tip::
+
+   **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.


What are we basing this recommendation of from regarding LLM being more accurate in JKC languages?

marianunez · 2026-03-05T20:51:05Z

source/administration-guide/manage/admin/autotranslation.rst

+
+Autotranslation is managed on a per-channel basis and is disabled by default for all channels. System admins and channel admins can enable or disable autotranslation for individual channels.
+
+- When autotranslation is enabled or disabled in a channel, a system post notifies channel members of the change.


We should also include that the messages will be translated starting from this point when enabled and not the history.

BenCookie95 added 2 commits March 4, 2026 16:05

add docs for autotranslations

991ef9a

model info

c92dcf4

BenCookie95 requested review from esethna and marianunez March 4, 2026 21:10

esethna requested a review from Combs7th March 5, 2026 00:05

esethna requested changes Mar 5, 2026

View reviewed changes

Combs7th added 1: Dev Review Requires review by a core commiter 2: Editor Review Requires review by an editor Guidance labels Mar 5, 2026

Combs7th added this to the v11.5.0 milestone Mar 5, 2026

marianunez approved these changes Mar 5, 2026

View reviewed changes


		Choosing an LLM for the Agents provider: Smaller, faster models are recommended for autotranslation. 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. A model like ``gpt-3.5-turbo`` provides accurate translations with lower latency.

		Manage autotranslation per channel


		From Mattermost v11.5, autotranslation automatically translates channel messages into each user's preferred display language. This enables multilingual teams to collaborate without language barriers.

		Autotranslation uses an asynchronous queue-based architecture. When a message is posted in a channel with autotranslation 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 toggle to view the original text at any time.


		Two translation provider options are available:

		- LibreTranslate: A self-hosted, open-source machine translation engine.


		.. tip::

		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.


		Autotranslation is managed on a per-channel basis and is disabled by default for all channels. System admins and channel admins can enable or disable autotranslation for individual channels.

		- When autotranslation is enabled or disabled in a channel, a system post notifies channel members of the change.

Conversation

BenCookie95 commented Mar 4, 2026

Summary

Ticket Link

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

esethna commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Combs7th commented Mar 5, 2026

Uh oh!

marianunez left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

esethna commented Mar 5, 2026 •

edited

Loading