Translating posts with a translation service
The server can translate a post when a reader asks, through a translation service that you configure: LibreTranslate,
DeepL, Google Cloud Translation, or Amazon Translate. A provider is built in when the server has its keys, and the
instance setting translation_providers enables it.
LibreTranslate
Section titled “LibreTranslate”LibreTranslate is open-source machine translation that you can run yourself, or use as a hosted service at libretranslate.com. Point the server at it with two settings of the configuration:
MY_TRANSLATOR_LIBRETRANSLATE_URL=http://libretranslate:5000# Only when the server asks for a key, as libretranslate.com does:MY_TRANSLATOR_LIBRETRANSLATE_API_KEY=your-keytranslator_libretranslate_urlis the base URL of the LibreTranslate server, withhttp:orhttps:and an optional path. A server on a private address works, such as a container next to this one orhttp://10.0.0.5:5000. The server does not follow redirects from it, so the key goes nowhere else.translator_libretranslate_api_keyis a secret, read only from the environment (MY_TRANSLATOR_LIBRETRANSLATE_API_KEYorMY_TRANSLATOR_LIBRETRANSLATE_API_KEY_FILE). Leave it unset when the server needs no key; a self-hosted one usually needs none. The key is never shown to clients or written to the logs.
Then add libretranslate to the instance setting translation_providers, in the order you want it tried, such as
translation_providers = libretranslate alone, or followed by another provider’s ID to fall back to it.
The server asks LibreTranslate for its list of languages before the first translation and again every hour, and does not send a post in a language pair that it does not list. When a post has no language, LibreTranslate detects it. Install the language models that your readers need on a server you run.
Translation quality varies by language. LibreTranslate’s models are good for some pairs and rough for others,
and a translation from a language with little training data can miss the meaning. Try the languages that your
community uses before you enable it, and keep a commercial provider after it in translation_providers if you need
one.
Where the text goes. A server that you run keeps the text of posts on your own machines, and no one else
receives it. Then you may allow it private and direct posts with translation_provider_visibilities, such as
libretranslate=public|local|unlisted|private|direct, and the
privacy policy lists no outside service for translation. A
hosted LibreTranslate, libretranslate.com or someone else’s, receives the text like any other provider: read its terms, keep the default
visibilities, and name it in the policy.
DeepL translates through its API with a key of a DeepL API plan. The server sends the text of a post with the markers that stand in for mentions, links, and decoration as XML elements, which DeepL keeps in place, and nothing else of the post.
-
Get an authentication key from your DeepL account. A key of the free plan ends in
:fx. -
Set it in the deployment configuration and restart the server:
Terminal window MY_TRANSLATOR_DEEPL_API_KEY=your-keyThe server calls
https://api-free.deepl.comfor a key of the free plan andhttps://api.deepl.comfor any other. To go through a proxy, setMY_TRANSLATOR_DEEPL_URL. The key is a secret: the server never logs it, puts it in an error, or shows it in a setting or an answer of the client API, and it sends it to that address only, following no redirects. -
Enable the provider with the instance setting
translation_providers, alone or in your order:Terminal window my instance set translation_providers deepl
The server asks DeepL which languages it translates when it first translates, and again each day. A post’s language
goes to the closest variant DeepL has: English to en-US, Portuguese to pt-BR, Chinese of Taiwan to zh-Hant. A
language that DeepL does not have goes to the next provider, or the reader is told that it cannot be translated.
Quota. Each plan has a monthly character quota, and a paid plan can have a cost limit that you set in your DeepL
account. When DeepL reports the quota or its rate limit, the server tries the next provider of translation_providers.
With none left, the reader sees that the post could not be translated right now, and the web client uses the browser’s
translation when you allow it. The server’s own monthly limits (translation_user_monthly_characters and
translation_server_monthly_characters) apply before any call, so set them below your DeepL quota. DeepL may count the
characters differently from them.
Data. Read DeepL’s terms before you enable it:
- On a paid plan, DeepL keeps the text and the translations only as long as it needs to translate them, and for at most 72 hours when it investigates an error.
- On the free plan, DeepL may keep the text and the translations for good, and its terms forbid sending personal data
through it. Posts usually contain personal data, so use the free plan only to try the provider out. Never allow it
privateordirectposts intranslation_provider_visibilities, and say in your privacy policy that DeepL keeps what it receives.
On a paid plan you can allow private and direct posts, provider by provider:
my instance set translation_provider_visibilities 'deepl=public|local|unlisted|private'Attribution. DeepL’s terms require that its name or logo is shown with each translation. The web client shows
“DeepL” with a link to https://www.deepl.com next to every translation from it, so you have nothing to add.
Google Cloud Translation
Section titled “Google Cloud Translation”Cloud Translation has the provider ID google. The server calls its
TranslateText method with the general translation model, and sends the text as HTML so that the mentions, links, and
other parts that must stay as they are come back in place.
- Enable the Cloud Translation API (
translate.googleapis.com) in the project that pays for the translations:gcloud services enable translate.googleapis.com --project PROJECT. - Grant the service account of the server
roles/cloudtranslate.useron that project:gcloud projects add-iam-policy-binding PROJECT --member serviceAccount:SA_EMAIL --role roles/cloudtranslate.user. - Set
MY_TRANSLATOR_GOOGLE_PROJECTto the project ID.MY_TRANSLATOR_GOOGLE_LOCATIONisglobalby default; it can name another location of Cloud Translation that serves the general model, such asus-central1. - Restart the server, and add
googleto the instance settingtranslation_providers.
On Google Cloud with the OpenTofu module mycroblog-gcp, the section
translation does the first three steps, and the apply restarts the service:
translation = {} # or { project_id = "other-project", location = "us-central1" }It enables the API in the deployment’s project, or in project_id, grants the service account of the service
roles/cloudtranslate.user there, and sets translator_google_project and translator_google_location. Then add google to
translation_providers.
The server authenticates with Application Default Credentials, like the other Google Cloud services it uses: on
Cloud Run, the service account of the service; elsewhere, the key file that GOOGLE_APPLICATION_CREDENTIALS names. No
API key is used. The server makes no call at start, so a missing API or role shows only when a reader asks for a
translation: the server then tries the next provider, and the reader sees that the translation failed when none is left.
A quota or rate limit of the project that Google reports also moves on to the next provider.
Google charges by the character sent, after a monthly free allowance; see Cloud Translation pricing. The server’s own monthly limits count the characters too, but not exactly as Google bills them, so set a budget alert in Cloud Billing as well.
Google states that it uses the text only to provide the translation, keeps it in memory only briefly, does not use it to train its models, and does not share it. The server calls the global endpoint of Cloud Translation, where Google does not keep the processing to one region.
Google’s attribution requirements ask that a translation be shown as
machine translated and that the “powered by Google Translate” badge appear next to it, linking to
https://translate.google.com. The web client shows the name “Google Translate” with that link next to every
translation by this provider. Google offers the badge images only as a download, so the server gives clients no logo for
this provider; check that what readers see meets Google’s requirements for your instance.
Amazon Translate
Section titled “Amazon Translate”Amazon Translate is the provider aws. The server calls its TranslateText operation with the credentials of the
AWS SDK’s default chain, as for the other AWS services: the execution role of the task or instance, the environment
variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or the shared credentials files. No key goes into the
server’s configuration.
- Give the role or user that the server runs as the IAM permission
translate:TranslateText. For a post whose language is unknown, Amazon Translate detects the language with Amazon Comprehend; AWS’s managed policies for Amazon Translate grantcomprehend:DetectDominantLanguagewith it, so grant that too. - Set
translator_aws_region(MY_TRANSLATOR_AWS_REGION) to the region of Amazon Translate, such asus-east-1. Detecting the language needs a region where Amazon Comprehend runs too. - Restart the server, then enable the provider with
translation_providers = aws, alone or in your order of preference among the others (instance settings).
On AWS with the OpenTofu module mycroblog-aws, the section
translation does the first two steps: translation = {} allows the tasks’ role both actions and sets
translator_aws_region to the region of the deployment, or to region when you give one. Then enable the provider.
Amazon Translate charges by the character sent, with a free tier for the first 12 months
(pricing). The server sends only the words of a post: mentions, hashtags,
links, and code stay on the server, and each of them goes as a short placeholder in HTML markup. Keep the monthly limits
of translation_user_monthly_characters and translation_server_monthly_characters within what you want to pay.
Amazon may store the text and use it to improve its services, possibly in another region, unless the AWS
Organizations AI services opt-out policy
covers the account. Without the opt-out, Amazon is not only your service provider for that text: say so in your
privacy policy (privacy policy template), and do not allow
private or direct for aws in translation_provider_visibilities. By default the provider receives only public,
local, and unlisted posts.
For LLMs and coding agents:this page as Markdown, llms.txt,llms-full.txt, llms-small.txt