# DeepL

Translate text and documents with DeepL, keep glossaries, improve text with DeepL Write, and check the account's usage.

## Connect DeepL

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `deepl` and choose **DeepL**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **API key · Required**: The DeepL API authentication key, such as 1a2b3c4d-…:fx for the free plan.

Paste a DeepL API key from your DeepL account (Account → API Keys). Keys of the free plan end in :fx and are sent to DeepL’s free API; any other key to DeepL API Pro.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in DeepL

Add a **DeepL** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Text](https://docs.gorunner.io/apps/deepl#fields-f-language): Translate
- [Document](https://docs.gorunner.io/apps/deepl#fields-f-document): Translate · Upload for Translation · Get Status · Download
- [Glossary](https://docs.gorunner.io/apps/deepl#fields-f-glossary): Create · Get · Get Many · Get Entries · Replace Entries · Rename · Delete
- [DeepL Write](https://docs.gorunner.io/apps/deepl#fields-f-write): Rephrase · Correct
- [Usage](https://docs.gorunner.io/apps/deepl#fields-f-usage): Get

To start a workflow from DeepL, use a [Schedule](https://docs.gorunner.io/apps/schedule), [Webhook](https://docs.gorunner.io/apps/webhook) or [Form](https://docs.gorunner.io/apps/form) trigger.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from DeepL can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When DeepL says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, DeepL is `pieceId: "deepl"` with `actionId: "deepl"`, set by `resource` and an `operation_…` field, such as `operation_document`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### DeepL › Text

### Translate

- **Text · Required**: The text to translate. A list from an earlier step ({{ }} that gives a list of texts) is translated item by item, in order.
- **Target Language · Required**: The language to translate into.
- **Source Language · Optional**: The text's language. Empty lets DeepL detect it.
- **Formality · Optional**: How formal the translation reads. "More" and "Less" fail for a target language without formality (German, French, Spanish, Japanese and others have it); the "if available" choices fall back quietly. Options: Default, More formal, Less formal, More formal, if available, Less formal, if available. Default: Default.
- **Glossary · Optional**: A glossary of this DeepL account.
- **Context · Optional**: Text around the text to translate, which guides the translation without being translated or billed.
- **Model · Optional**: DeepL's choice by default; the quality model where it exists, or the faster one. Options: DeepL's choice, Quality, if available, Quality only, Faster.
- **Text Is · Optional**: Plain text, or HTML / XML whose tags DeepL keeps as they are. Options: Plain text, HTML, XML.
- **Split Sentences · Optional**: Where DeepL splits the text into sentences: at punctuation and new lines, at punctuation only, or nowhere (the text is one sentence). Options: Punctuation and new lines, Punctuation only, Don't split. Default: Punctuation and new lines.
- **Preserve Formatting · Optional**: Keep the text's punctuation and upper/lower case at the start and end of sentences as they are. Off by default.

### DeepL › Document

### Translate and Upload for Translation

- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). At most 11 MB. DeepL reads the format from the file name's extension.
- **Target Language · Required**: The language to translate into.
- **Source Language · Optional**: The document's language. Empty lets DeepL detect it; a glossary needs it.
- **Formality · Optional**: How formal the translation reads; the "if available" choices fall back quietly for a language without formality. Options: Default, More formal, Less formal, More formal, if available, Less formal, if available. Default: Default.
- **Glossary · Optional**: A glossary of this DeepL account.
- **Output Format · Optional**: A file extension to convert to, such as docx for a PDF. Empty keeps the document's format.

### Get Status

- **Document ID · Required**: The document_id Upload for Translation returned.
- **Document Key · Required**: The document_key Upload for Translation returned; DeepL keeps no copy of it.

### Download

- **Document ID · Required**: The document_id Upload for Translation returned.
- **Document Key · Required**: The document_key Upload for Translation returned; DeepL keeps no copy of it.
- **File Name · Optional**: The name the downloaded file gets, such as report-de.docx. Empty uses the name DeepL sends, or translated.\<extension>.

### DeepL › Glossary

### Create

- **Name · Required**: The glossary's name (at most 1,024 bytes).
- **Source Language · Required**: The language the terms are written in.
- **Target Language · Required**: The language the terms translate into.
- **Entries · Required**: One term per line: the source term, a tab (or a comma, for CSV), then its translation. An object from an earlier step ({"Invoice": "Rechnung"}) works too.
- **Entries Format · Optional**: How the Entries text separates a term from its translation. Options: Tab separated, Comma separated (CSV). Default: Tab separated.

### Get and Delete

- **Glossary · Required**: A glossary of this DeepL account.

### Get Many

- **Return All · Optional**: Read every glossary, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many glossarys to return (1–1000). Default: 50. Shows when **Return All** is off.

### Get Entries

- **Glossary · Required**: A glossary of this DeepL account.
- **Source Language · Required**: The language the terms are written in.
- **Target Language · Required**: The language the terms translate into.

### Replace Entries

- **Glossary · Required**: A glossary of this DeepL account.
- **Source Language · Required**: The language the terms are written in.
- **Target Language · Required**: The language the terms translate into.
- **Entries · Required**: One term per line: the source term, a tab (or a comma, for CSV), then its translation. An object from an earlier step ({"Invoice": "Rechnung"}) works too.
- **Entries Format · Optional**: How the Entries text separates a term from its translation. Options: Tab separated, Comma separated (CSV). Default: Tab separated.

### Rename

- **Glossary · Required**: A glossary of this DeepL account.
- **Name · Required**: The glossary's name (at most 1,024 bytes).

### DeepL › DeepL Write

### Rephrase

- **Text · Required**: The text to improve. A list from an earlier step is improved item by item, in order.
- **Language · Optional**: The language of the result. Empty keeps the text's own; another one also translates it. Options: Same as the text, de, en-GB, en-US, es, fr, it, ja, ko, pt-BR, pt-PT, zh-Hans.
- **Writing Style · Optional**: A style for the audience. Set a style or a tone, not both. The "if available" choices fall back to the default for a language without styles. Options: Default, Simple, Business, Academic, Casual, Simple, if available, Business, if available, Academic, if available, Casual, if available. Default: Default.
- **Tone · Optional**: A tone for the text. Set a style or a tone, not both. Options: Default, Friendly, Confident, Diplomatic, Enthusiastic, Friendly, if available, Confident, if available, Diplomatic, if available, Enthusiastic, if available. Default: Default.

### Correct

- **Text · Required**: The text to improve. A list from an earlier step is improved item by item, in order.
- **Language · Optional**: The language of the result. Empty keeps the text's own; another one also translates it. Options: Same as the text, de, en-GB, en-US, es, fr, it, ja, ko, pt-BR, pt-PT, zh-Hans.

### DeepL › Usage

### Get

Nothing to fill in.

Source: https://docs.gorunner.io/apps/deepl