> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# tool_deepl

A RocketRide tool node that gives an agent DeepL translation and text-rephrasing functions, with node defaults for common translation requests.

## About DeepL

DeepL is the external translation and rephrasing API this node calls over HTTPS. This node uses its translation endpoint and its Write rephrasing endpoint to process one text value or a batch.

## What it does

Use this node when an agent must translate text or rewrite it in a requested style or tone. It exposes tools only—there are no pipeline lanes—and returns a structured result plus the first result as a convenient `text` field. Pick it over a general LLM transformation when an API translation target, detected source language, or DeepL Write result is required.

## As a tool

The registered prefix is `deepl`, so the agent sees `deepl.deepl_translate` and `deepl.deepl_write`.

| Function | Description |
|---|---|
| `deepl.deepl_translate` | Translates text into a target language. |
| `deepl.deepl_write` | Rephrases text with an optional writing style or tone. |

### `deepl.deepl_translate`

`text` is required and accepts one non-empty string or a list of at most 50 non-empty strings. `target_lang` uses the call value when present and otherwise falls back to **Default Target Language**; `source_lang` is optional and is sent only when non-blank. Optional `formality`, `model_type`, boolean `preserve_formatting`, and non-blank `context` are added to the request when valid. The result is `success`, `translations`, first-result `text`, and `error`; invalid input or request failures return `success: false` with an empty result list and an error message.

### `deepl.deepl_write`

`text` has the same one-string-or-up-to-50-strings rule. Optional `target_lang` is restricted to `de`, `en-GB`, `en-US`, `es`, `fr`, `it`, `ja`, `ko`, `pt-BR`, `pt-PT`, or `zh`. Supply either optional `writing_style` or `tone`, never both; supplying both returns a failure without making an HTTP request. The result is `success`, `improvements`, first-result `text`, and `error`; invalid input or request failures use the same failure shape.

## Configuration

Set the API key, then configure the values that should be used when a translation call omits them. A valid tool-call argument takes precedence over a configured default.

### Default Target Language

This is the fallback target for `deepl_translate` and defaults to `EN-US`. Leave it as the common target for the node's callers, or set it to another target so agents do not need to repeat it. If neither the call nor configuration provides a non-blank target, translation returns an error.

### Formality

This is the fallback formality for translation and defaults to `default`. The supported values are `default`, `more`, `less`, `prefer_more`, and `prefer_less`; a valid call value overrides it. Change it when the translated output needs a consistent level of formality, while noting that unsupported target-language combinations are returned by DeepL as errors rather than silently ignored. A cleared or invalid default is omitted from the request when no valid call value is supplied.

### Model Type

This optional translation fallback defaults to empty, which omits it and lets the service choose. Valid values are `latency_optimized`, `quality_optimized`, and `prefer_quality_optimized`; a valid call value takes precedence. Set it only when this node needs a consistent quality or latency preference, and keep it blank when no preference should be sent.

## Authentication

Provide **API Key** or set `ROCKETRIDE_DEEPL_KEY`; a non-blank configuration key takes precedence over the environment variable. The node fails startup if neither is set. Keys ending in `:fx` use the free API host; other keys use the standard API host. The key is sent in the authorization header and is not included in returned request errors.

## Notes

### Request and error handling

Invalid text batches are rejected before an HTTP request. The node sends requests through the shared retrying POST helper and returns a structured failure for request errors or unexpected response bodies. It provides specific safe messages for quota exhaustion, authentication failure, and rate limiting.

## Upstream docs

- [DeepL API documentation](https://developers.deepl.com/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_deepl.apikey` | `string` | **API Key**<br/>DeepL API key (from https://www.deepl.com/pro-api). A key ending in :fx is a Free-tier key and is routed to api-free.deepl.com automatically. | `""` |
| `tool_deepl.formality` | `string` | **Formality**<br/>Default formality for translation. Only honored by a subset of target languages; DeepL returns an error for unsupported ones, which the node surfaces. | `"default"` |
| `tool_deepl.modelType` | `string` | **Model Type**<br/>Translation model to request. Empty lets DeepL choose its default. quality_optimized favors quality, latency_optimized favors speed, prefer_quality_optimized uses quality where available and otherwise falls back. | `""` |
| `tool_deepl.targetLang` | `string` | **Default Target Language**<br/>Default target language for translation when the agent does not supply one. Regional variants are allowed (e.g. EN-US, EN-GB, PT-BR, PT-PT, ZH-HANS, ZH-HANT). | `"EN-US"` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_deepl)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->
