DeepL · sjsyrek · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -650,9 +650,13 @@ deepl write "Fresh improvement please." --lang en-US --no-cache
 - Spanish (`es`)
 - French (`fr`)
 - Italian (`it`)
+- Japanese (`ja`)
+- Korean (`ko`)
 - Portuguese (`pt`) - generic, defaults to Brazilian Portuguese
 - Portuguese - Brazilian (`pt-BR`)
 - Portuguese - European (`pt-PT`)
+- Chinese (`zh`) - generic, defaults to Simplified Chinese
+- Chinese - Simplified (`zh-Hans`)
 
 **Writing Styles:**
 
@@ -1043,22 +1047,24 @@ DeepL CLI includes built-in retry logic and timeout handling for robust API comm
 
 **Automatic Retry Logic:**
 
-- Automatically retries failed requests on transient errors (5xx, network failures)
-- Default: 3 retries with exponential backoff
-- Does not retry on client errors (4xx - bad request, auth failures, etc.)
-- Exponential backoff delays: 1s, 2s, 4s, 8s, 10s (capped at 10s)
+- Idempotent requests (GET, HEAD, PUT, DELETE) are retried on 5xx responses and transient network failures
+- Non-idempotent requests (POST — translations, uploads, glossary and key creation) are replayed only when the error proves the request never reached the server (connection refused, DNS failure), so a slow response can never be submitted and billed twice
+- Rate limiting (429) is retried for all methods, honoring the `Retry-After` header when the server sends one
+- Other client errors (4xx — bad request, auth failures, etc.) are not retried
+- Default: 3 retries with full-jitter exponential backoff (capped at 10s)
 
 **Timeout Configuration:**
 
-- Default timeout: 30 seconds per request
+- Default timeout: 30 seconds per request, with an overall time budget across retries
 - Applies to all API requests (translate, usage, languages, etc.)
+- Override per invocation with the global `--timeout <ms>` and `--max-retries <n>` flags
 
 **Features:**
 
 - ✅ Automatic retry on transient failures
 - ✅ Exponential backoff to avoid overwhelming the API
-- ✅ Smart error detection (retries 5xx, not 4xx)
-- ✅ Configurable via library-consumer options; not exposed as a CLI flag
+- ✅ Retry policy aware of request idempotency
+- ✅ Configurable via `--timeout` / `--max-retries` (or library-consumer options)
 - ✅ Works across all DeepL API endpoints
 
 **Retry Behavior Examples:**
@@ -1072,11 +1078,12 @@ deepl translate "Hello" --to es
 deepl translate "Hello" --to es
 # Fails immediately without retries on auth errors
 
-# Rate limiting (429) - does not retry
-# You may want to wait before retrying manually
+# Rate limiting (429) - retried automatically
+# Honors the Retry-After header when the server sends one,
+# otherwise falls back to jittered exponential backoff
 ```
 
-**Note:** Retry and timeout settings use sensible defaults optimized for the DeepL API. These are internal features that work automatically - no configuration required.
+**Note:** Retry and timeout settings use sensible defaults optimized for the DeepL API. No configuration is required; `--timeout` and `--max-retries` are available when a specific invocation needs different bounds (e.g. very large documents on a slow uplink).
 
 ### Glossaries
 
@@ -1331,7 +1338,7 @@ Cache location: `~/.cache/deepl-cli/cache.db` (or `~/.deepl-cli/cache.db` for le
 
 ### Prerequisites
 
-- Node.js >= 20.19.0
+- Node.js >= 24.0.0
 - npm >= 9.0.0
 - DeepL API key
 

diff --git a/docs/API.md b/docs/API.md
@@ -1,7 +1,7 @@
 # DeepL CLI - API Reference
 
-**Version**: 1.2.0
-**Last Updated**: April 25, 2026
+**Version**: 2.0.0
+**Last Updated**: July 29, 2026
 
 Complete reference for all DeepL CLI commands, options, and configuration.
 
@@ -52,8 +52,12 @@ Options that work with all commands:
 --verbose, -v       Show extra information (source language, timing, cache status)
 --config, -c FILE   Use alternate configuration file
 --no-input          Disable all interactive prompts (abort instead of prompting)
+--timeout MS        HTTP request timeout in milliseconds (default: 30000)
+--max-retries N     Maximum automatic retries for retryable requests (default: 3)
 ```
 
+Automatic retries apply to idempotent requests, and to rate-limited (429) responses for every method; a request that submits work is otherwise never replayed. Retries share a wall-clock budget of twice `--timeout`, so raising `--max-retries` alone does not extend how long the CLI waits on an unresponsive endpoint.
+
 **Examples:**
 
 ```bash
@@ -78,6 +82,9 @@ deepl --quiet translate docs/ --to es --output docs-es/
 # Use custom config file
 deepl --config ~/.deepl-work.json translate "Hello" --to es
 
+# Give a large document more time, and disable automatic retries
+deepl --timeout 120000 --max-retries 0 translate report.pdf --to de
+
 # Use custom config directory (via environment variable)
 export DEEPL_CONFIG_DIR=/path/to/config
 deepl translate "Hello" --to es
@@ -730,9 +737,13 @@ When `--style` or `--tone` is set for a target language that does not support it
 - `es` - Spanish
 - `fr` - French
 - `it` - Italian
+- `ja` - Japanese
+- `ko` - Korean
 - `pt` - Portuguese (generic, defaults to Brazilian Portuguese)
 - `pt-BR` - Brazilian Portuguese
 - `pt-PT` - European Portuguese
+- `zh` - Chinese (generic, defaults to Simplified Chinese)
+- `zh-Hans` - Simplified Chinese
 
 #### Examples
 
@@ -1134,7 +1145,7 @@ Interactive setup wizard that creates `.deepl-sync.yaml` by scanning the project
 - `--path GLOB` - Source file path or glob pattern
 - `--sync-config PATH` - Path to `.deepl-sync.yaml`
 
-`--source-lang` and `--target-langs` are accepted as deprecated aliases for one minor release and emit a stderr warning; they will be removed in the next major release. `deepl translate --target-lang` is unchanged — it operates on strings and stays aligned with the DeepL API's wire name.
+`--source-lang` and `--target-langs` were accepted as deprecated aliases during `1.x` and were removed in `2.0.0`; use `--source-locale` / `--target-locales`. `deepl translate --target-lang` is unchanged — it operates on strings and stays aligned with the DeepL API's wire name.
 
 **Examples:**
 
@@ -3071,7 +3082,7 @@ Unclassified failure: emitted when an error escapes every typed handler and matc
 
 Authentication failed or no API key is available. Emitted by:
 
-- `deepl auth set-key`, `deepl auth test` when the key cannot be validated
+- `deepl auth set-key` when the key cannot be validated
 - Every command that touches the API (`translate`, `write`, `voice`, `glossary`, `usage`, `sync`, `tm list`, `admin`, etc.) when `DEEPL_API_KEY` is unset and no key is in the config file
 - HTTP 401/403 responses from the DeepL API
 
@@ -3113,7 +3124,7 @@ Remediation: re-read the command's `--help` and the relevant section of this API
 The configuration file or a configuration value is invalid. Emitted by:
 
 - `deepl config set` with a key that is not in the schema, or a value that fails validation (invalid language code, invalid formality, invalid output format, non-positive cache size, non-HTTPS `baseUrl`, path-traversal attempts)
-- `deepl config get/unset` with a malformed key
+- `deepl config get` with a malformed key
 - Any command that loads the config file when the file fails to parse, is missing a required field, or specifies an unsupported version
 - `sync` when `.deepl-sync.yaml` is missing required fields, has invalid locales, or declares an unsupported version
 - `sync push` / `sync pull` when the remote TMS returns 401/403 (surfaced as `ConfigError` with a hint to check `TMS_API_KEY` / `TMS_TOKEN` and the relevant YAML fields)
@@ -3230,5 +3241,5 @@ deepl write --check README.md
 
 ---
 
-**Last Updated**: April 20, 2026
-**DeepL CLI Version**: 1.1.0
+**Last Updated**: July 29, 2026
+**DeepL CLI Version**: 2.0.0
diff --git a/docs/SYNC.md b/docs/SYNC.md
@@ -476,7 +476,7 @@ deepl sync init [OPTIONS]
 | `--path <glob>` | Source file path or glob pattern |
 | `--sync-config <path>` | Path to `.deepl-sync.yaml` (default: auto-detect) |
 
-`--source-lang` and `--target-langs` remain accepted as deprecated aliases for one minor release and emit a stderr deprecation warning; they will be removed in the next major release. The `--locale` filter on `sync push` / `pull` / `status` / `export` is unchanged. `deepl translate --target-lang` is unchanged — it operates on strings and stays aligned with the DeepL API's wire name.
+`--source-lang` and `--target-langs` were accepted as deprecated aliases during `1.x` and were removed in `2.0.0`; use `--source-locale` and `--target-locales`. The `--locale` filter on `sync push` / `pull` / `status` / `export` is unchanged. `deepl translate --target-lang` is unchanged — it operates on strings and stays aligned with the DeepL API's wire name.
 
 **Examples:**
 
@@ -793,7 +793,7 @@ Each target locale's approved dictionary is fetched exactly once per `sync pull`
 
 ### Worked example
 
-`deepl sync init` currently accepts `--source-lang` and `--target-langs` as deprecated aliases for `--source-locale` and `--target-locales` (shipped via commit `d65cbb3`). Both aliases emit a stderr deprecation warning pointing at the replacement flag. Under the policy above, these aliases will be removed at the `2.0` cut — this is confirmed, and the removal will not slip into any `1.x` release. See the [`deepl sync init`](#deepl-sync-init) section for the current accepted synopsis.
+`deepl sync init` accepted `--source-lang` and `--target-langs` as deprecated aliases for `--source-locale` and `--target-locales` throughout `1.x`; both emitted a stderr deprecation warning pointing at the replacement flag. Per the policy above, the aliases were removed at the `2.0` cut — since `2.0.0` they fail as unknown options. See the [`deepl sync init`](#deepl-sync-init) section for the current accepted synopsis.
 
 ## CI/CD Integration
 
@@ -861,7 +861,7 @@ The `.deepl-sync.lock` file is only staged when this sync run actually wrote an
 ```yaml
 i18n-check:
   stage: test
-  image: node:20
+  image: node:24
   script:
     - npm install -g @deepl/cli
     - deepl sync --frozen

diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -139,7 +139,7 @@ Common issues and solutions when using the DeepL CLI.
 
 2. For batch/directory translation, the CLI uses concurrency control internally. Avoid running multiple CLI instances simultaneously on the same API key.
 
-3. The CLI automatically retries with exponential backoff (1s, 2s, 4s, up to 10s, max 3 retries). If errors persist, wait and try again.
+3. Retries honor the server's `Retry-After` header when present, falling back to full-jitter exponential backoff (max 3 retries by default; see the global `--max-retries` flag). If errors persist, wait and try again.
 
 ---
 
@@ -167,7 +167,7 @@ Common issues and solutions when using the DeepL CLI.
    export HTTP_PROXY=http://proxy.example.com:8080
    ```
 
-4. The CLI retries on transient network errors automatically with exponential backoff.
+4. The CLI retries idempotent requests on transient network errors automatically. Requests that submit work (translations, document uploads, glossary creation) are replayed only when the error proves the request never reached the server, so they are never double-billed — for those, rerun the command (exit code 5 is safe to retry at the script level).
 
 ### "Request failed with status code 503"
 
@@ -183,7 +183,7 @@ Common issues and solutions when using the DeepL CLI.
    deepl translate "Hello" --to es --no-cache
    ```
 
-3. The CLI automatically retries on 503 errors with exponential backoff. If the error persists, the API may be experiencing an extended outage.
+3. Read-only requests are retried automatically on 503. Requests that submit work (translate, document upload) surface the error immediately so they are never double-billed; retry them at the script level (exit code 5). If the error persists, the API may be experiencing an extended outage.
 
 ---
 

diff --git a/src/api/document-client.ts b/src/api/document-client.ts
@@ -16,11 +16,19 @@ interface DeepLDocumentStatusResponse {
   error_message?: string;
 }
 
+/** Uploads and downloads move whole files, so they need far more headroom
+ *  than the interactive request timeout. */
+const TRANSFER_TIMEOUT_MS = 300_000;
+
 export class DocumentClient extends HttpClient {
   constructor(apiKey: string, options: DeepLClientOptions = {}) {
     super(apiKey, options);
   }
 
+  private get transferTimeout(): number {
+    return Math.max(this.requestTimeout, TRANSFER_TIMEOUT_MS);
+  }
+
   async uploadDocument(
     file: Buffer,
     options: DocumentTranslationOptions
@@ -69,7 +77,8 @@ export class DocumentClient extends HttpClient {
               ...formData.getHeaders(),
             },
           };
-        }
+        },
+        { timeout: this.transferTimeout }
       );
 
       return {
@@ -101,6 +110,11 @@ export class DocumentClient extends HttpClient {
     }
   }
 
+  /**
+   * The result endpoint is effectively single-use: a replayed download can
+   * consume the result of an already-billed translation and lose it
+   * permanently, so this request is never retried.
+   */
   async downloadDocument(handle: DocumentHandle): Promise<Buffer> {
     try {
       const response = await this.makeRawRequest<Buffer>(
@@ -116,7 +130,8 @@ export class DocumentClient extends HttpClient {
             },
             responseType: 'arraybuffer',
           };
-        }
+        },
+        { maxRetries: 0, timeout: this.transferTimeout }
       );
 
       return Buffer.from(response);