> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/deepl.md).

# DeepL

Translate text and documents, manage glossaries, and inspect DeepL usage.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| DeepL     | API Key        |

#### DeepL

Connect to DeepL with a developer API key for translation and glossaries.

**Set up in DeepL**

1. Prepare the DeepL account or service that the workflow will access. Grant access to the required resources and operations.
2. **API Key:** Create a DeepL developer API key. Admin API keys are not supported.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **DeepL**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required                 | What to enter                                                                                                                                                                                                                                             |
| ------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes                      | Create a DeepL developer API key. Admin API keys are not supported. [Provider instructions](https://developers.deepl.com/docs/getting-started/auth).                                                                                                      |
| API Region    | Optional / as applicable | The DeepL API region assigned to this account. Select 'us' or 'jp' only when DeepL has enabled that regional endpoint for the account; otherwise use 'eu'. [Provider instructions](https://developers.deepl.com/docs/getting-started/regional-endpoints). |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **DeepL** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Translate Text

Translate text into another language with optional tone, context, formatting, and glossary controls.

**Required permissions:** `translate:text`, `languages:read`, `glossaries:read`.

**Inputs**

| Field                    | Type            | Required | Description                                                                                                                                                                |
| ------------------------ | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text                     | textarea        | Yes      | The text to translate.                                                                                                                                                     |
| Target language          | select (string) | Yes      | The DeepL language code to translate the text into. Options load from the selected connection.                                                                             |
| Source language          | select (string) | No       | The DeepL code for the original language, or blank for automatic detection. Options load from the selected connection.                                                     |
| Translation context      | textarea        | No       | Background that helps DeepL choose the right translation but is not translated or billed.                                                                                  |
| Formality                | select (string) | No       | How formal the translation should sound when the target language supports it. Available values: Default, More formal, Less formal, Prefer more formal, Prefer less formal. |
| Translation model        | select (string) | No       | The DeepL model preference, or blank to use the account default. Available values: Quality optimized, Prefer quality optimized, Latency optimized.                         |
| Preserve formatting      | boolean         | No       | Keep the source text's formatting even when DeepL would normally correct it. Default: false.                                                                               |
| Return billed characters | boolean         | No       | Include the number of characters DeepL counted for billing. Default: true.                                                                                                 |
| Glossary ID              | select (string) | No       | The DeepL glossary ID whose language pair matches this translation. Options load from the selected connection.                                                             |
| Tag handling             | select (string) | No       | Treat markup in the source as XML or HTML. Available values: XML, HTML.                                                                                                    |

**Outputs**

| Field                         | Type     | Description                                                 |
| ----------------------------- | -------- | ----------------------------------------------------------- |
| Translated text               | textarea | The translated text.                                        |
| Detected source language code | string   | The DeepL source-language code detected or used.            |
| Billed characters             | integer  | Characters counted for billing when requested.              |
| Model used                    | string   | The DeepL model that handled the translation when reported. |

#### Translate Document

Upload a document from a public HTTPS URL and start a DeepL translation job, preserving its format unless a supported output format is selected.

**Required permissions:** `translate:document`, `languages:read`, `glossaries:read`.

**Inputs**

| Field            | Type            | Required | Description                                                                                                                                                  |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Document URL     | string          | Yes      | A publicly reachable HTTPS link to the document to translate.                                                                                                |
| Filename         | string          | No       | The document filename including its extension, or blank to use the URL filename.                                                                             |
| Target language  | select (string) | Yes      | The DeepL language code to translate the document into. Options load from the selected connection.                                                           |
| Source language  | select (string) | No       | The DeepL code for the document's original language, or blank for automatic detection. Options load from the selected connection.                            |
| Output format    | string          | No       | A supported output extension, or blank to keep the input format. Legacy DOC inputs are returned as DOCX.                                                     |
| Formality        | select (string) | No       | How formal the translated document should sound when supported. Available values: Default, More formal, Less formal, Prefer more formal, Prefer less formal. |
| Glossary ID      | select (string) | No       | The DeepL glossary ID whose language pair matches this document translation. Options load from the selected connection.                                      |
| Add AI watermark | boolean         | No       | Add DeepL's AI-generated watermark when the output is DOCX or PDF. Default: false.                                                                           |

**Outputs**

| Field        | Type   | Description                                                                                                                                                                      |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Document ID  | string | The ID of the DeepL document translation job.                                                                                                                                    |
| Document key | secret | The per-document secret key returned by Translate Document for this job. Retain it until the translated file is downloaded, and handle it securely. It is not the DeepL API key. |

#### Get Document Translation Status

Check whether a DeepL document translation is queued, translating, done, or failed.

**Required permissions:** `translate:document`.

**Inputs**

| Field        | Type   | Required | Description                                                                                                                                                        |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Document ID  | string | Yes      | The document job ID returned by Translate Document.                                                                                                                |
| Document key | secret | Yes      | The per-document secret key returned by Translate Document. Retain it until the translated file is downloaded and handle it securely. It is not the DeepL API key. |

**Outputs**

| Field              | Type    | Description                                              |
| ------------------ | ------- | -------------------------------------------------------- |
| Document ID        | string  | The checked document job ID.                             |
| Translation status | select  | The current document translation state.                  |
| Seconds remaining  | integer | DeepL's estimate while the document is translating.      |
| Billed characters  | integer | The billable character count when DeepL reports it.      |
| Translation error  | string  | The document translation error when the status is error. |

#### Download Translated Document

Download a completed DeepL document translation.

**Required permissions:** `translate:document`.

**Inputs**

| Field               | Type   | Required | Description                                                                              |
| ------------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| Document ID         | string | Yes      | The completed document job ID returned by Translate Document.                            |
| Document key        | secret | Yes      | The per-document secret key returned with this document ID. It is not the DeepL API key. |
| Downloaded filename | string | No       | Optional filename for the stored translated document, including its extension.           |

**Outputs**

| Field        | Type    | Description                                               |
| ------------ | ------- | --------------------------------------------------------- |
| Download URL | string  | A temporary URL for downloading the translated document.  |
| Filename     | string  | The filename used to store the translated document.       |
| Content type | string  | The MIME type DeepL reported for the translated document. |
| Size (bytes) | integer | The downloaded translated document size in bytes.         |
| Document ID  | string  | The downloaded DeepL document job ID.                     |

#### Create Glossary

Create a DeepL multilingual glossary with one CSV or TSV dictionary.

**Required permissions:** `glossaries:write`, `languages:read`, `glossaries:read`.

**Inputs**

| Field            | Type            | Required | Description                                                                                                                                              |
| ---------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Glossary name    | string          | Yes      | A recognizable name for the glossary.                                                                                                                    |
| Source language  | select (string) | Yes      | The root language code used by the source phrases. Options load from the selected connection.                                                            |
| Target language  | select (string) | Yes      | The root language code used by the translated phrases. Options load from the selected connection.                                                        |
| Glossary entries | textarea        | Yes      | Source and translated phrase pairs: two fields per TSV row, or two or four fields per CSV row. Four-field CSV rows for other language pairs are ignored. |
| Entries format   | select (string) | No       | Whether entry pairs are tab-separated or comma-separated. Available values: Tab-separated values (TSV), Comma-separated values (CSV). Default: tsv.      |

**Outputs**

| Field                | Type     | Description                                 |
| -------------------- | -------- | ------------------------------------------- |
| Glossary ID          | string   | The ID assigned to the new glossary.        |
| Glossary name        | string   | The created glossary's name.                |
| Source language code | string   | The dictionary's root source-language code. |
| Target language code | string   | The dictionary's root target-language code. |
| Entry count          | integer  | The number of phrase pairs DeepL accepted.  |
| Created at           | datetime | When DeepL created the glossary.            |

#### Get Usage

Report current DeepL account and API-key usage and limits.

**Required permissions:** `usage:read`.

**Inputs**

No input fields are required in this catalog entry.

**Outputs**

| Field                            | Type          | Description                                                                                             |
| -------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| Characters used                  | integer       | Characters used in the current billing period across text translation, document translation, and Write. |
| Character limit                  | integer       | The account's current-period character limit.                                                           |
| Documents translated             | integer       | Documents translated in the current period when DeepL reports it.                                       |
| Document limit                   | integer       | The current-period document limit when DeepL reports it.                                                |
| Team documents translated        | integer       | Documents translated by the team in the current period.                                                 |
| Team document limit              | integer       | The team's current-period document limit.                                                               |
| Product usage                    | object\_array | Per-product account and API-key usage when the Pro plan reports it.                                     |
| API-key characters used          | integer       | Characters used by this API key when the plan reports it.                                               |
| API-key character limit          | integer       | The character limit assigned to this API key.                                                           |
| Speech-to-text milliseconds used | integer       | Deprecated speech-to-text milliseconds used when DeepL reports it.                                      |
| Speech-to-text millisecond limit | integer       | Deprecated speech-to-text millisecond limit when DeepL reports it.                                      |
| Speech-to-text minutes used      | integer       | Speech-to-text minutes used in the current period.                                                      |
| Speech-to-text minute limit      | integer       | The current-period speech-to-text minute limit.                                                         |
| Speech-to-speech minutes used    | integer       | Speech-to-speech minutes used in the current period.                                                    |
| Speech-to-speech minute limit    | integer       | The current-period speech-to-speech minute limit.                                                       |
| Billing period start             | datetime      | When the reported billing period starts.                                                                |
| Billing period end               | datetime      | When the reported billing period ends.                                                                  |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/deepl.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
