DeepL - Loco

Accessing the DeepL Free and Pro APIs from Loco

You will need a DeepL API subscription in order to access v2 of their API. Be sure to subscribe to the correct plan.

https://www.deepl.com/pro#developer

Configure a bot to use DeepL

Navigate to the Bots tab wherever you see the :robot icon: in the Loco dashboard.
Click "New bot", choose DeepL, and enter your DeepL API key into the only text field.
Save the bot and it's ready to run. See also how to run a translation bot.

Steps for generating a DeepL API key

Get a DeepL account and subscribe to any API plan.
Go to your DeepL account settings and copy the Authentication Key to your clipboard.

API versions and DeepL plans

Loco supports v2 and v3 of the DeepL API only. You must be subscribed to DeepL API Free or DeepL API Pro to use these versions of the API. We recommend you start with their free plan, and upgrade to a paid plan if your usage requires it.

Other DeepL plans use the v1 API. Loco has no support for the older API. It is not publicly documented and DeepL require special permission to integrate with it.

If you have any questions about DeepL plans and how they relate to API access, please ask DeepL support.

Supported languages

Loco tries to map your project locales to DeepL's supported languages, but you may find that regional variations aren't supported:

Unsupported variants will be reduced to the base language. e.g. fr-FR and fr-CA will both be sent as just fr.
Supported variants will be mapped in full, e.g. zh-Hant and zh-Hans are both valid target languages.
Locales without a common language tag won't be mapped, even if they're very similar. For example: DeepL supports Bokmål (nb), but has no support for Nynorsk (no).

If you find DeepL translations lack regional specificity you might consider a glossary to manage term differences. However, note in the caveats that DeepL glossaries don't support variants.

Tone / formality

Loco supports formality variance via your project locale settings (not via the DeepL bot settings). Whatever you configure in your project locale will be used for DeepL translation via their API, as follows:

Setting formal / polite will send formality=prefer_more
Setting informal / plain will send formality=prefer_less

Note that DeepL only supports formality for a subset of languages. The above parameters fail silently if unsupported for the target locale.

Glossary support

You can use DeepL glossaries by nominating a Loco project as the source of language pairs. This is for Loco Pro accounts only.

To configure DeepL to use a glossary from Loco: create a new bot, or open its settings from the :cog icon:. Then select a Loco project from the dropdown list. If you don't see this option, either you have a free account, or there are no projects available.

Any Loco project can be set as a glossary, but only language pairs supported by DeepL can be used in translation, and only within the size restrictions; e.g. 1024 bytes maximum per term. Please read DeepL's documentation.

Every time you run your DeepL bot, Loco will sync the required language pairs to a DeepL v3 glossary. It will adopt a name like "Loco #1234 (My Glossary)". You can inspect this in your DeepL dashboard, but you should avoid renaming or editing it manually.

If you have existing DeepL glossaries, you can import them into Loco as tab-separated, or comma-separated files. See Importing glossary pairs. Likewise you can export your Loco glossary projects to suitable dictionary files and use them elsewhere. See Exporting glossary pairs.

Glossary caveats

No language variants
For example: pt-PT and pt-BR are both supported target languages in DeepL, but a glossary language can only be PT. This makes it impossible to maintain separate European and Brazilian dictionaries within the same DeepL glossary. A further problem occurs if your Loco glossary project contains both pt-PT and pt-BR, as they may continually overwrite each other in the DeepL PT dictionary.
Single glossary for DeepL API Free
If you need more than one glossary, you'll need the DeepL API Pro plan. Loco can only create a new DeepL glossary if your account has room for it. If your DeepL quota is exceeded, the glossary will simply not be used.

Context support

DeepL's API supports a context parameter, but this is applied to all translations in a batch of source texts. This makes it impractical for providing information about individual texts, because it prevents multiple sources being sent in bulk.

Loco's support for this feature works as follows:

If you configure a default context value in the DeepL bot, this will be sent to DeepL for all translation requests using that same bot instance. This usage is akin to an AI prompt, where you might add a few sentences about what your translations are for.
If there is no default context, and you translate just one item, Loco will send both the context and notes properties of your asset to DeepL. This may produce a better translation than processing multiple texts at once.

LLM support

Loco uses DeepL's lower latency "classic" translation model by default, but you can enable their "next-gen" model by selecting it from the model dropdown in the bot settings.

The "next-gen" option uses specialized LLMs for higher quality translation, at the cost of slower responses. DeepL claims they outperform general purpose LLMs for this task. See for yourself and let us know.